@sabaiway/agent-workflow-kit 1.8.0 → 1.8.1

package/CHANGELOG.md

@@ -4,6 +4,37 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 1.8.1 — Fix: `npx … init` ran nothing (the installer's own run-guard mis-fired under npx)
+
+1.8.0 set out to fix "`npx <pkg> init` quietly did nothing" — and shipped a *second*, unrelated
+silent no-op in the same spot. The reported symptom: `npx @sabaiway/agent-workflow-kit@latest init`
+installs the package, prints the npx "Ok to proceed?" line, and then **prints nothing and does
+nothing** — none of 1.8.0's new DX messaging, no install, exit 0.
+
+Root cause: the bottom-of-file run-guard that gates `main()` so importing the module has no side
+effects:
+
+```js
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+```
+
+npx never runs `bin/install.mjs` by its real path — it runs the `node_modules/.bin/agent-workflow-kit`
+**symlink** to it. Node resolves `import.meta.url` to the real file but leaves `process.argv[1]` as the
+symlink path, so the string compare is always false, `main()` never runs, and the process exits 0
+without a word. (Running `node bin/install.mjs` directly — as the test suite did — has no symlink, which
+is why every test passed while real `npx` was broken.)
+
+- **Fix:** the guard now compares **real paths** (`realpathSync` on both sides), which collapses the
+  `.bin` symlink so direct and npx invocations both register as a direct run; it also holds under
+  `--preserve-symlinks`. Import-with-no-`argv[1]` and a missing file still fall through to `false`, so
+  importing the module continues to run nothing.
+- **Regression test:** a new case invokes the installer **through a symlink** (the exact `.bin` shim
+  npx uses) and asserts it both prints and writes the payload — the previous suite never exercised a
+  symlinked invocation, so the bug slipped through.
+
+Installer bugfix only — no `docs/ai` structural change, deployment-lineage head stays **`1.3.0`**, no
+migration.
+
 ## 1.8.0 — Stale-version DX: `@latest` everywhere + a no-network never-downgrade gate
 
 A returning user ran the headline `npx @sabaiway/agent-workflow-kit init` and it quietly did nothing:

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.8.0'
+  version: '1.8.1'
 ---
 
 # agent-workflow-kit

package/bin/install.mjs

@@ -23,9 +23,9 @@
 // Dependency-free, Node >= 18.
 
 import { readFile, mkdir } from 'node:fs/promises';
-import { existsSync, lstatSync } from 'node:fs';
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { copyTreeRefresh } from '../tools/fs-safe.mjs';
@@ -274,7 +274,22 @@ To update the kit later, re-run:  npx @sabaiway/agent-workflow-kit@latest init`)
 
 // Run main() only when executed directly (npx / node bin/install.mjs), never on import — so tests
 // can import this module to assert it has no side effects. Same idiom as tools/detect-backends.mjs.
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+//
+// Compare by REAL path, not by URL string: npx invokes the bin through a symlink in node_modules/.bin,
+// so process.argv[1] is that symlink while import.meta.url is the resolved real file — a raw string
+// compare reads them as different, main() never runs, and `npx … init` exits silently (the reported
+// "nothing happens after install" bug). realpathSync collapses the symlink so both sides match; it also
+// holds under --preserve-symlinks. A bare `node -e` (no argv[1]) and a missing file (realpath throws)
+// both correctly fall through to false — importing the module still runs nothing.
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
 if (isDirectRun) {
   main().catch((err) => {
     console.error(err);

package/bin/install.test.mjs

@@ -78,6 +78,31 @@ describe('kit installer — payload + symlink-traversal hardening', () => {
   });
 });
 
+describe('kit installer — runs through the npx bin symlink', () => {
+  let dir;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'aw-kit-symlink-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('main() runs when invoked through a symlink (the node_modules/.bin shim npx uses)', async () => {
+    // npx never runs bin/install.mjs by its real path — it runs node_modules/.bin/agent-workflow-kit,
+    // a symlink to it. Node resolves import.meta.url to the REAL file but leaves argv[1] as the symlink,
+    // so a string compare of the two makes isDirectRun false and main() silently no-ops. Reproduce that
+    // exact invocation: run the installer via a symlink and assert it actually installed (visible output
+    // + payload on disk). A regression here means `npx … init` goes quiet again.
+    const shim = join(dir, 'agent-workflow-kit'); // stands in for node_modules/.bin/<name>
+    await symlink(INSTALLER, shim);
+    const target = join(dir, 'home', 'agent-workflow-kit');
+    const res = spawnSync(process.execPath, [shim, '--dir', target, '--no-launchers'], { encoding: 'utf8' });
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /installed v|updated the kit/);
+    assert.ok(existsSync(join(target, 'SKILL.md')), 'install through the symlink must write the payload');
+  });
+});
+
 describe('kit installer — module hygiene', () => {
   it('importing install.mjs runs nothing (main() is guarded by isDirectRun)', () => {
     // `node -e` has no argv[1], so isDirectRun is false → importing must not run main()

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",