@sabaiway/agent-workflow-kit 1.11.0 → 1.12.0

package/tools/fs-safe.mjs

@@ -4,15 +4,20 @@
 // unit-testable without touching the real filesystem; the defaults are Node's SYNC fs (matching the
 // tools/ detector style). Dependency-free, Node >= 18.
 //
-// Three primitives:
+// Five primitives:
 //   assertContainedRealPath — refuse to write through/into a symlink, or to a dest outside a root.
 //   copyTreeRefresh         — recursive copy that OVERWRITES regular files (refresh), SKIPS a symlink
 //                             whose dest already exists (additive), and guards every dest component.
 //   linkManaged             — create/keep ONLY a symlink we own; STOP (typed ManagedLinkConflict) on
 //                             a foreign symlink or a non-symlink dest; refuse a symlinked source.
+//   removeTreeManaged       — the inverse of copyTreeRefresh: recursively remove a dir/file ONLY when
+//                             it (and its path) is not reached through a symlink and stays within root.
+//   unlinkManaged           — the inverse of linkManaged: remove ONLY a symlink whose target is ours;
+//                             STOP (typed ManagedLinkConflict) on a foreign symlink or a non-symlink.
 
 import {
   lstatSync, existsSync, mkdirSync, readdirSync, copyFileSync, readlinkSync, symlinkSync,
+  rmSync, unlinkSync,
 } from 'node:fs';
 import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
 
@@ -130,3 +135,47 @@ export const linkManaged = (src, dest, root, deps = {}) => {
     { dest, expected: src, found: target },
   );
 };
+
+// Recursively remove a managed dir/file — the inverse of copyTreeRefresh. `assertContainedRealPath`
+// guards `target` first: it refuses a `target` outside `root`, and refuses when `root`, any
+// intermediate component, OR `target` itself is a symlink — so we never delete *through* or *at* a
+// symlink (a symlinked skill dir is a STOP, not a follow-and-delete). A recursive `rm` does NOT
+// follow symlinks *inside* the tree (Node unlinks a symlink entry rather than recursing into its
+// target), so an internal symlink is removed safely without touching what it points at. Outcomes:
+// 'removed', or 'noop' when the target is already absent. Dependency-injected (lstat / rm).
+export const removeTreeManaged = (target, root, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const rm = deps.rm ?? ((p) => rmSync(p, { recursive: true, force: true }));
+  assertContainedRealPath(root, target, deps);
+  if (lstatNoFollow(target, lstat) === null) return 'noop';
+  rm(target);
+  return 'removed';
+};
+
+// Remove ONLY a symlink we own — the inverse of linkManaged. Guards the PARENT chain (root +
+// intermediate dirs) the same way linkManaged does (the leaf IS the managed symlink, so it is
+// inspected, not traversal-rejected). Outcomes: 'unlinked' (a symlink whose resolved target is our
+// `expectedSrc` — including a dangling-but-ours link), 'noop' (dest absent), or a thrown
+// ManagedLinkConflict (a non-symlink, or a symlink pointing elsewhere — never removed).
+export const unlinkManaged = (dest, expectedSrc, root, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const readlink = deps.readlink ?? readlinkSync;
+  const unlink = deps.unlink ?? unlinkSync;
+
+  assertContainedRealPath(root, dirname(dest), deps);
+  const existing = lstatNoFollow(dest, lstat);
+  if (existing === null) return 'noop';
+  if (!existing.isSymbolicLink()) {
+    throw managedLinkConflict(`refusing to remove a non-symlink at ${dest}`, { dest, found: 'file' });
+  }
+  const target = readlink(dest);
+  const resolvedTarget = isAbsolute(target) ? target : resolve(dirname(dest), target);
+  if (resolvedTarget !== resolve(expectedSrc)) {
+    throw managedLinkConflict(
+      `refusing to remove a foreign symlink at ${dest} (points at ${target}, not our ${expectedSrc})`,
+      { dest, expected: expectedSrc, found: target },
+    );
+  }
+  unlink(dest);
+  return 'unlinked';
+};

package/tools/fs-safe.test.mjs

@@ -9,6 +9,8 @@ import {
   assertContainedRealPath,
   copyTreeRefresh,
   linkManaged,
+  removeTreeManaged,
+  unlinkManaged,
   MANAGED_LINK_CONFLICT,
 } from './fs-safe.mjs';
 
@@ -204,3 +206,141 @@ describe('linkManaged', () => {
     assert.throws(() => linkManaged(srcDir, join(root, 'cmd'), root), /regular file/i);
   });
 });
+
+// ── removeTreeManaged ───────────────────────────────────────────────────────────
+
+describe('removeTreeManaged', () => {
+  it('recursively removes a managed dir tree', () => {
+    const root = join(dir, 'skills');
+    const skill = join(root, 'agent-workflow-kit');
+    mkdirSync(join(skill, 'tools'), { recursive: true });
+    writeFileSync(join(skill, 'SKILL.md'), 'x');
+    writeFileSync(join(skill, 'tools', 'a.mjs'), 'y');
+    const result = removeTreeManaged(skill, root);
+    assert.equal(result, 'removed');
+    assert.equal(existsSync(skill), false);
+    assert.equal(existsSync(root), true); // only the target went, not the parent
+  });
+
+  it('is a no-op when the target is already absent', () => {
+    const root = join(dir, 'skills');
+    mkdirSync(root);
+    assert.equal(removeTreeManaged(join(root, 'gone'), root), 'noop');
+  });
+
+  it('STOPs on a symlinked target (never follows + deletes through it)', () => {
+    const root = join(dir, 'skills');
+    const real = join(dir, 'real-skill');
+    mkdirSync(root);
+    mkdirSync(real);
+    writeFileSync(join(real, 'keep.txt'), 'keep');
+    symlinkSync(real, join(root, 'agent-workflow-kit')); // the skill dir is a symlink
+    assert.throws(() => removeTreeManaged(join(root, 'agent-workflow-kit'), root), /symlink/i);
+    assert.equal(existsSync(join(real, 'keep.txt')), true); // the target it pointed at is untouched
+  });
+
+  it('removes a symlink ENTRY inside the tree without touching what it points at', () => {
+    const root = join(dir, 'skills');
+    const skill = join(root, 'agent-workflow-kit');
+    const outside = join(dir, 'outside');
+    mkdirSync(skill, { recursive: true });
+    mkdirSync(outside);
+    writeFileSync(join(outside, 'precious.txt'), 'precious');
+    symlinkSync(outside, join(skill, 'link-to-outside')); // an internal symlink
+    removeTreeManaged(skill, root);
+    assert.equal(existsSync(skill), false);
+    assert.equal(existsSync(join(outside, 'precious.txt')), true); // never recursed through the link
+  });
+
+  it('refuses a target outside the root', () => {
+    const root = join(dir, 'skills');
+    mkdirSync(root);
+    assert.throws(() => removeTreeManaged(join(dir, 'elsewhere'), root), /outside/);
+  });
+
+  it('rm is injectable (no real deletion when injected)', () => {
+    const root = join(dir, 'skills');
+    const skill = join(root, 'agent-workflow-kit');
+    mkdirSync(skill, { recursive: true });
+    let removed = null;
+    const result = removeTreeManaged(skill, root, { rm: (p) => { removed = p; } });
+    assert.equal(result, 'removed');
+    assert.equal(removed, skill);
+    assert.equal(existsSync(skill), true); // the injected rm did nothing
+  });
+});
+
+// ── unlinkManaged ───────────────────────────────────────────────────────────────
+
+describe('unlinkManaged', () => {
+  const makeSrc = () => {
+    const src = join(dir, 'src.sh');
+    writeFileSync(src, '#!/bin/sh\n');
+    return src;
+  };
+
+  it('unlinks a symlink that points at our source', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    symlinkSync(src, dest);
+    const result = unlinkManaged(dest, src, root);
+    assert.equal(result, 'unlinked');
+    assert.equal(existsSync(dest), false);
+    assert.equal(existsSync(src), true); // the source it pointed at is untouched
+  });
+
+  it('is a no-op when the dest is absent', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    assert.equal(unlinkManaged(join(root, 'cmd'), src, root), 'noop');
+  });
+
+  it('STOPs on a non-symlink dest (typed ManagedLinkConflict)', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    writeFileSync(dest, 'someone-elses-file');
+    assert.throws(() => unlinkManaged(dest, src, root), (err) => err.code === MANAGED_LINK_CONFLICT);
+    assert.equal(readFileSync(dest, 'utf8'), 'someone-elses-file'); // untouched
+  });
+
+  it('STOPs on a foreign symlink (points elsewhere)', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    const foreign = join(dir, 'foreign.sh');
+    writeFileSync(foreign, '#!/bin/sh\n');
+    symlinkSync(foreign, dest);
+    assert.throws(() => unlinkManaged(dest, src, root), (err) => err.code === MANAGED_LINK_CONFLICT);
+    assert.equal(readlinkSync(dest), foreign); // untouched
+  });
+
+  it('removes a dangling symlink that still textually points at our source', () => {
+    const src = join(dir, 'src.sh'); // never created → the link is dangling
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    symlinkSync(src, dest);
+    assert.equal(unlinkManaged(dest, src, root), 'unlinked');
+    assert.equal(lstatSync(root).isDirectory(), true);
+    assert.equal(existsSync(dest), false);
+  });
+
+  it('unlink is injectable', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    symlinkSync(src, dest);
+    let unlinked = null;
+    const result = unlinkManaged(dest, src, root, { unlink: (p) => { unlinked = p; } });
+    assert.equal(result, 'unlinked');
+    assert.equal(unlinked, dest);
+    assert.equal(existsSync(dest), true); // the injected unlink did nothing
+  });
+});

package/tools/manifest/validate.mjs

@@ -77,7 +77,9 @@ const readSkillVersion = (text) => {
 
 // Authoritative version source: package.json where one exists, else SKILL.md
 // frontmatter metadata.version. So a bridge (no package.json) can't drift from its SKILL.md.
-const readAuthoritativeVersion = (skillDir) => {
+// Exported so the family registry (tools/family-registry.mjs) reports an INSTALLED member's
+// version from the SAME authoritative source the validator checks — no second, drifting reader.
+export const readAuthoritativeVersion = (skillDir) => {
   const pkgPath = join(skillDir, 'package.json');
   if (existsSync(pkgPath)) {
     try {

package/tools/uninstall.integration.test.mjs

@@ -0,0 +1,144 @@
+// Integration acceptance for the guarded uninstaller against the REAL filesystem — what the mocked
+// unit test cannot prove: real validateManifest over real skill dirs, real removeTreeManaged deleting
+// a real tree, real unlinkManaged removing OUR symlink while leaving a FOREIGN one, a real marker
+// pre-commit hook removed, and user-authored docs/ai LEFT INTACT after a full --yes teardown. The
+// git-backed fence unhide is delegated to hideFootprint (already covered by its own integration test),
+// so it is injected here as a recording stub — this test owns the uninstaller's own fs mutations.
+
+import { describe, it, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, symlinkSync, existsSync, lstatSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { buildPlan, executePlan, SAFE_REMOVE, MANAGED_MARKER, REPORT_ONLY, STOP } from './uninstall.mjs';
+import { surveyFamily, surveyProject } from './family-registry.mjs';
+import { START_MARKER } from './hide-footprint.mjs';
+
+const made = [];
+const mkdtemp = (tag) => { const d = mkdtempSync(join(tmpdir(), tag)); made.push(d); return d; };
+afterEach(() => { while (made.length) { try { rmSync(made.pop(), { recursive: true, force: true }); } catch { /* best effort */ } } });
+
+const writeFile = (p, s) => { mkdirSync(join(p, '..'), { recursive: true }); writeFileSync(p, s); };
+
+// A minimal but VALID family skill dir (passes the real validateManifest: family/schema/kind/version
+// match + SKILL.md metadata.version == capability.json version + role sources exist).
+const makeMemorySkill = (skillsRoot) => {
+  const dir = join(skillsRoot, 'agent-workflow-memory');
+  writeFile(join(dir, 'SKILL.md'), "---\nname: agent-workflow-memory\nmetadata:\n  version: '1.1.1'\n---\n# memory\n");
+  writeFile(join(dir, 'capability.json'), JSON.stringify({
+    family: 'agent-workflow', schema: 1, name: 'agent-workflow-memory', kind: 'memory-substrate',
+    version: '1.1.1', provides: ['context'], roles: {},
+    detect: { installed: { env: 'AGENT_WORKFLOW_MEMORY_DIR', default: '~/.claude/skills/agent-workflow-memory', file: 'SKILL.md' } },
+  }));
+  return dir;
+};
+
+const makeCodexBridge = (skillsRoot) => {
+  const dir = join(skillsRoot, 'codex-cli-bridge');
+  writeFile(join(dir, 'SKILL.md'), "---\nname: codex-cli-bridge\nmetadata:\n  version: '1.0.0'\n---\n# codex\n");
+  writeFile(join(dir, 'bin', 'codex-exec.sh'), '#!/bin/sh\n');
+  writeFile(join(dir, 'bin', 'codex-review.sh'), '#!/bin/sh\n');
+  writeFile(join(dir, 'capability.json'), JSON.stringify({
+    family: 'agent-workflow', schema: 1, name: 'codex-cli-bridge', kind: 'execution-backend',
+    version: '1.0.0', provides: ['execute', 'review'],
+    roles: {
+      execute: { cmd: 'codex-exec', source: 'bin/codex-exec.sh' },
+      review: { cmd: 'codex-review', source: 'bin/codex-review.sh' },
+    },
+    detect: { installed: { env: 'CODEX_CLI_BRIDGE_DIR', default: '~/.claude/skills/codex-cli-bridge', file: 'SKILL.md' } },
+  }));
+  return dir;
+};
+
+describe('uninstall integration (real fs)', () => {
+  it('plans + applies a full guarded teardown: removes ours, keeps foreign + user-authored', () => {
+    const home = mkdtemp('aw-unh-home-');
+    const skills = mkdtemp('aw-unh-skills-');
+    const bindir = mkdtemp('aw-unh-bin-');
+    const proj = mkdtemp('aw-unh-proj-');
+    const foreignTarget = mkdtemp('aw-unh-foreign-');
+
+    const memorySkill = makeMemorySkill(skills);
+    const codexSkill = makeCodexBridge(skills);
+
+    // ~/.local/bin wrappers: codex-exec is OURS; codex-review is a FOREIGN symlink (must be kept).
+    symlinkSync(join(codexSkill, 'bin/codex-exec.sh'), join(bindir, 'codex-exec'));
+    writeFileSync(join(foreignTarget, 'codex-review'), '#!/bin/sh\n');
+    symlinkSync(join(foreignTarget, 'codex-review'), join(bindir, 'codex-review'));
+
+    // Project surfaces: a hidden fence, OUR marker pre-commit hook, and user-authored docs/ai.
+    writeFile(join(proj, '.git/info/exclude'), `# user rule\n${START_MARKER}\n/AGENTS.md\n# <<< agent-workflow-kit hidden mode <<<\n`);
+    writeFile(join(proj, '.git/hooks/pre-commit'), '#!/usr/bin/env bash\n# myproj:install-git-hooks.mjs\nset -e\nnode scripts/check-docs-size.mjs\n');
+    writeFile(join(proj, 'docs/ai/handover.md'), '# handover (USER-AUTHORED)\n');
+    writeFile(join(proj, 'docs/ai/.workflow-version'), '1.3.0\n');
+
+    // Resolve only memory + codex as installed (env-pointed); other members fall to <home>/.claude → absent.
+    const deps = {
+      getenv: { AGENT_WORKFLOW_MEMORY_DIR: memorySkill, CODEX_CLI_BRIDGE_DIR: codexSkill },
+      home,
+    };
+    const family = surveyFamily(deps);
+    const project = surveyProject(proj, deps);
+    assert.equal(project.hiddenFence, true);
+    assert.equal(family.find((m) => m.name === 'agent-workflow-memory').manifestState, 'ok');
+    assert.equal(family.find((m) => m.name === 'codex-cli-bridge').manifestState, 'ok');
+
+    const plan = buildPlan({ family, project, projectDir: proj, bindir }, deps);
+    const cls = (surface, pred) => plan.items.find((i) => i.surface === surface && pred(i));
+    assert.equal(cls('skill', (i) => i.member === 'agent-workflow-memory').class, SAFE_REMOVE);
+    assert.equal(cls('wrapper', (i) => i.path.endsWith('codex-exec')).class, MANAGED_MARKER);
+    assert.equal(cls('wrapper', (i) => i.path.endsWith('codex-review')).class, STOP); // foreign
+    assert.equal(cls('fence', () => true).class, MANAGED_MARKER);
+    assert.equal(cls('hook', () => true).class, MANAGED_MARKER);
+    assert.equal(cls('docs', (i) => i.path.endsWith('docs/ai')).class, REPORT_ONLY);
+
+    // Apply. Inject a recording fence-unhide (its real git path is covered by hide-footprint's own test).
+    const unhideCalls = [];
+    const r = executePlan(plan, { yes: true }, { ...deps, hideFootprint: (opts) => { unhideCalls.push(opts); return { action: 'unhidden' }; } });
+
+    // Ours is gone:
+    assert.equal(existsSync(memorySkill), false, 'memory skill dir removed');
+    assert.equal(existsSync(codexSkill), false, 'codex skill dir removed');
+    assert.equal(existsSync(join(bindir, 'codex-exec')), false, 'our wrapper symlink removed');
+    assert.equal(existsSync(join(proj, '.git/hooks/pre-commit')), false, 'marker hook removed');
+    assert.equal(r.unhidden, true);
+    // The fence is validated by a dry-run unhide in preflight, then unhidden for real in the mutate phase.
+    assert.deepEqual(unhideCalls, [{ dir: proj, unhide: true, dryRun: true }, { dir: proj, unhide: true }]);
+
+    // Foreign + user-authored is KEPT:
+    assert.equal(lstatSync(join(bindir, 'codex-review')).isSymbolicLink(), true, 'foreign wrapper kept');
+    assert.equal(existsSync(join(foreignTarget, 'codex-review')), true, 'foreign target untouched');
+    assert.equal(existsSync(join(proj, 'docs/ai/handover.md')), true, 'user-authored docs/ai NEVER deleted');
+  });
+
+  it('preflight refuses (zero mutation) when a skill dir turns foreign between plan and apply', () => {
+    const home = mkdtemp('aw-unh2-home-');
+    const skills = mkdtemp('aw-unh2-skills-');
+    const memorySkill = makeMemorySkill(skills);
+    const deps = { getenv: { AGENT_WORKFLOW_MEMORY_DIR: memorySkill }, home };
+
+    const family = surveyFamily(deps);
+    const plan = buildPlan({ family }, deps);
+    assert.equal(plan.items.find((i) => i.surface === 'skill').class, SAFE_REMOVE);
+
+    // Corrupt the manifest after planning → the preflight re-check must STOP, leaving the dir intact.
+    writeFileSync(join(memorySkill, 'capability.json'), '{ not json');
+    assert.throws(() => executePlan(plan, { yes: true }, deps), (err) => err.code === 'UNINSTALL_STOP');
+    assert.equal(existsSync(memorySkill), true, 'skill dir untouched after a refused preflight');
+  });
+
+  it('keeps a pre-commit hook whose marker was removed between plan and apply', () => {
+    const home = mkdtemp('aw-unh3-home-');
+    const proj = mkdtemp('aw-unh3-proj-');
+    writeFile(join(proj, '.git/hooks/pre-commit'), '#!/usr/bin/env bash\n# myproj:install-git-hooks.mjs\nset -e\n');
+    const deps = { getenv: {}, home };
+
+    const plan = buildPlan({ family: [], project: surveyProject(proj, deps), projectDir: proj }, deps);
+    assert.equal(plan.items.find((i) => i.surface === 'hook').class, MANAGED_MARKER);
+
+    // The user rewrites the hook (dropping our marker) before they apply the teardown.
+    writeFileSync(join(proj, '.git/hooks/pre-commit'), '#!/bin/sh\n# my own hook now\n');
+    assert.throws(() => executePlan(plan, { yes: true }, deps), (err) => err.code === 'UNINSTALL_STOP');
+    assert.equal(existsSync(join(proj, '.git/hooks/pre-commit')), true, 'a now-unmarked (user) hook is NEVER deleted');
+  });
+});