Add CLI preflight command

Author: s1oopX

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.7 - 2026-06-17
+
+- Added a read-only CLI `preflight` command that checks runtime prerequisites,
+  packaged source files, and target directory state before initialization.
+- Documented the preflight command in the Chinese and English READMEs.
+- Added smoke coverage for fresh and existing target preflight results.
+
 ## 0.1.6 - 2026-06-17
 
 - Added a Node wrapper `upgrade` command for safe template upgrades of existing

README.en.md

@@ -344,6 +344,12 @@ Preview initialization through the Node wrapper:
 npx github:s1oopX/agent-memory-workflow init --target "$HOME\.agents" --dry-run
 ```
 
+Run a read-only preflight check before initialization:
+
+```powershell
+npx github:s1oopX/agent-memory-workflow preflight --target "$HOME\.agents"
+```
+
 Upgrade an existing directory through the Node wrapper. This is the safe upgrade
 mode: it overwrites workflow-managed files, creates backups, and preserves
 existing machine facts under `machine\` by default:
@@ -491,7 +497,7 @@ Short term:
 Medium term:
 
 - provide a more complete CLI experience
-- add preflight checks before initialization
+- strengthen preflight checks before initialization
 - add migration helpers for future workflow-version changes
 
 Long term:

README.md

@@ -326,6 +326,12 @@ npx github:s1oopX/agent-memory-workflow init --target "$HOME\.agents"
 npx github:s1oopX/agent-memory-workflow init --target "$HOME\.agents" --dry-run
 ```
 
+通过 Node 包装器执行初始化前预检，不写入文件：
+
+```powershell
+npx github:s1oopX/agent-memory-workflow preflight --target "$HOME\.agents"
+```
+
 通过 Node 包装器升级已有目录。该命令等价于安全升级模式，会自动覆盖工作流托管文件、创建备份，并默认保留 `machine\` 下已有的机器事实：
 
 ```powershell
@@ -454,7 +460,7 @@ SDK 适合在出现稳定应用边界后再引入。数据库适合需要并发
 中期：
 
 - 提供更完整的 CLI 体验
-- 增加初始化前预检
+- 增强初始化前预检
 - 增加未来工作流版本迁移辅助
 
 长期：

README.zh-CN.md

@@ -326,6 +326,12 @@ npx github:s1oopX/agent-memory-workflow init --target "$HOME\.agents"
 npx github:s1oopX/agent-memory-workflow init --target "$HOME\.agents" --dry-run
 ```
 
+通过 Node 包装器执行初始化前预检，不写入文件：
+
+```powershell
+npx github:s1oopX/agent-memory-workflow preflight --target "$HOME\.agents"
+```
+
 通过 Node 包装器升级已有目录。该命令等价于安全升级模式，会自动覆盖工作流托管文件、创建备份，并默认保留 `machine\` 下已有的机器事实：
 
 ```powershell
@@ -454,7 +460,7 @@ SDK 适合在出现稳定应用边界后再引入。数据库适合需要并发
 中期：
 
 - 提供更完整的 CLI 体验
-- 增加初始化前预检
+- 增强初始化前预检
 - 增加未来工作流版本迁移辅助
 
 长期：

bin/agent-memory-workflow.js

@@ -14,6 +14,7 @@ function usage() {
 Usage:
   agent-memory-workflow init [--target <path>] [--force] [--dry-run] [--backup-root <path>] [--no-backup] [--overwrite-machine-facts] [--skip-verify]
   agent-memory-workflow upgrade [--target <path>] [--dry-run] [--backup-root <path>] [--no-backup] [--overwrite-machine-facts] [--skip-verify]
+  agent-memory-workflow preflight [--target <path>]
   agent-memory-workflow verify [--root <path>]
   agent-memory-workflow status [--root <path>]
   agent-memory-workflow show-paths [--root <path>]
@@ -22,6 +23,7 @@ Usage:
 Examples:
   agent-memory-workflow init --target "$HOME/.agents"
   agent-memory-workflow init --target "$HOME/.agents" --dry-run
+  agent-memory-workflow preflight --target "$HOME/.agents"
   agent-memory-workflow upgrade --target "$HOME/.agents"
   agent-memory-workflow verify --root "$HOME/.agents"
   agent-memory-workflow status --root "$HOME/.agents"
@@ -165,6 +167,75 @@ function printPaths(root) {
   console.log(`initializer=${paths.initializer}`);
 }
 
+function sourcePaths() {
+  return {
+    templates: path.join(repoRoot, "templates"),
+    bootstrapTemplate: path.join(repoRoot, "templates", "AGENT_BOOTSTRAP.md"),
+    initializer: path.join(repoRoot, "tools", "init-agent-memory-workflow.ps1"),
+    verifier: path.join(repoRoot, "tools", "verify-agent-memory-workflow.ps1"),
+  };
+}
+
+function runPreflight(target) {
+  const resolvedTarget = path.resolve(target);
+  const paths = workflowPaths(resolvedTarget);
+  const sources = sourcePaths();
+  const failures = [];
+
+  console.log("Agent memory workflow preflight");
+  console.log(`CLI version: ${packageJson.version}`);
+  console.log(`Node: ${process.version}`);
+
+  const pwshVersion = spawnSync("pwsh", ["--version"], { encoding: "utf8" });
+  if (pwshVersion.error && pwshVersion.error.code === "ENOENT") {
+    failures.push("PowerShell 7 executable `pwsh` was not found on PATH.");
+    console.log("PowerShell: missing");
+  } else if (pwshVersion.error) {
+    failures.push(pwshVersion.error.message);
+    console.log("PowerShell: error");
+  } else {
+    console.log(`PowerShell: ${pwshVersion.stdout.trim() || "available"}`);
+  }
+
+  console.log(`Source templates: ${formatPresent(sources.templates)}`);
+  console.log(`Bootstrap template: ${formatPresent(sources.bootstrapTemplate)}`);
+  console.log(`Source initializer: ${formatPresent(sources.initializer)}`);
+  console.log(`Source verifier: ${formatPresent(sources.verifier)}`);
+
+  if (!exists(sources.templates)) failures.push(`Missing source templates: ${sources.templates}`);
+  if (!exists(sources.bootstrapTemplate)) failures.push(`Missing bootstrap template: ${sources.bootstrapTemplate}`);
+  if (!exists(sources.initializer)) failures.push(`Missing source initializer: ${sources.initializer}`);
+  if (!exists(sources.verifier)) failures.push(`Missing source verifier: ${sources.verifier}`);
+
+  const manifest = readManifest(paths.manifest);
+  console.log(`Target: ${resolvedTarget}`);
+  console.log(`Target exists: ${exists(resolvedTarget) ? "yes" : "no"}`);
+  console.log(`Target manifest: ${formatPresent(paths.manifest)}`);
+  if (manifest?.parseError) {
+    console.log(`Target manifest parse: failed (${manifest.parseError})`);
+  } else if (manifest) {
+    console.log(`Target workflow version: ${manifest.version ?? "unknown"}`);
+  }
+
+  if (!exists(resolvedTarget)) {
+    console.log("Target mode: fresh install");
+  } else if (manifest) {
+    console.log("Target mode: existing workflow");
+  } else {
+    console.log("Target mode: existing non-workflow directory");
+  }
+
+  if (failures.length > 0) {
+    console.log("Result: FAIL");
+    for (const failure of failures) {
+      console.log(`- ${failure}`);
+    }
+    process.exit(1);
+  }
+
+  console.log("Result: PASS");
+}
+
 function runDoctor(root) {
   const resolvedRoot = path.resolve(root);
   const paths = workflowPaths(resolvedRoot);
@@ -241,6 +312,13 @@ function main() {
     return;
   }
 
+  if (command === "preflight") {
+    validateOptions(args, { valueOptions: ["--target"] });
+    const target = readOption(args, "--target", path.join(os.homedir(), ".agents"));
+    runPreflight(target);
+    return;
+  }
+
   if (command === "upgrade") {
     runInit(args, { force: true });
     return;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-memory-workflow",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Local-first file protocol for shared agent memory.",
   "license": "MIT",
   "type": "commonjs",

tools/test-agent-memory-workflow.ps1

@@ -84,6 +84,14 @@ try {
         }
     }
 
+    Invoke-Step "node wrapper preflights fresh target" {
+        $preflightOutput = (& node $cliScript preflight --target $dryRunTarget) -join "`n"
+        if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+        Assert-TextContains -Text $preflightOutput -Needle "Target exists: no" -Context "fresh preflight output"
+        Assert-TextContains -Text $preflightOutput -Needle "Target mode: fresh install" -Context "fresh preflight output"
+        Assert-TextContains -Text $preflightOutput -Needle "Result: PASS" -Context "fresh preflight output"
+    }
+
     Invoke-Step "force preserves machine facts by default" {
         $machineFile = Join-Path $target "machine\MACHINE_ENVIRONMENT_MEMORY.md"
         $sentinel = "LOCAL_SENTINEL_MACHINE_FACT"
@@ -123,6 +131,14 @@ try {
         Assert-FileContains -Path $machineFile -Needle $sentinel
     }
 
+    Invoke-Step "node wrapper preflights existing target" {
+        $preflightOutput = (& node $cliScript preflight --target $target) -join "`n"
+        if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+        Assert-TextContains -Text $preflightOutput -Needle "Target exists: yes" -Context "existing preflight output"
+        Assert-TextContains -Text $preflightOutput -Needle "Target mode: existing workflow" -Context "existing preflight output"
+        Assert-TextContains -Text $preflightOutput -Needle "Result: PASS" -Context "existing preflight output"
+    }
+
     Invoke-Step "node wrapper prints package version" {
         $versionOutput = ((& node $cliScript --version) -join "`n").Trim()
         if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }