@ghl-ai/aw 0.1.44-beta.0 → 0.1.44-beta.2

package/c4/commandSurface.mjs

@@ -0,0 +1,286 @@
+/**
+ * c4/commandSurface.mjs — slash-command resolution per harness (G3).
+ *
+ * Why: intent-based routing fires via the slim card / SessionStart hook,
+ * but a user typing `/aw:plan` directly relies on a per-harness slash
+ * command surface. Without these symlinks (or, on Claude, the plugin
+ * marketplace registration), `/aw:plan` errors out and the AC for
+ * "manual command works" fails.
+ *
+ * Naming convention (verified, L4): ECC ships UN-PREFIXED command files
+ * (`plan.md`, `build.md`, …). Slash namespacing is by SUBDIRECTORY:
+ *   ~/.cursor/commands/aw/<name>.md  → /aw:<name>
+ *   ~/.codex/commands/aw/<name>.md   → /aw:<name>
+ * The legacy `~/.cursor/commands/aw-<name>.md` shape is NOT what the
+ * pilot transcripts produced and is not what we install.
+ *
+ * Per-harness behavior:
+ *   - claude-web: 'noop' — plugin marketplace (registered separately by
+ *     claudePluginRegistry.mjs) exposes the ECC commands directly.
+ *   - cursor-cloud / codex-web: 'symlink' — link each ECC command into
+ *     the harness command dir, replacing stale symlinks idempotently.
+ *
+ * `expectedCommands` is derived at runtime by globbing
+ * `<eccHome>/commands/*.md` and filtering to the AW routing-stage list.
+ * No hardcoded array drives the install; ECC is the source of truth.
+ *
+ * Contract: spec.md::§"c4/commandSurface.mjs", tasks.md::3.7.
+ */
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readlinkSync,
+  symlinkSync,
+  unlinkSync,
+} from 'node:fs';
+import { join, basename, extname } from 'node:path';
+
+// Canonical AW routing-stage commands. Anything in <eccHome>/commands/*.md
+// not on this list is treated as "not a slash-command" (e.g. README.md).
+// This list is a filter applied AFTER globbing; it is not a source of truth
+// for what gets installed — only what we recognize as a stage.
+const AW_STAGE_COMMANDS = new Set([
+  'plan',
+  'build',
+  'investigate',
+  'review',
+  'test',
+  'deploy',
+  'ship',
+  'feature',
+  'adk',
+  'publish',
+]);
+
+/**
+ * Walk <eccHome>/commands/*.md and return the AW-stage basenames in
+ * alphabetical order. Stage filename matching is case-sensitive (ECC ships
+ * lowercase).
+ *
+ * @param {string} eccHome
+ * @returns {string[]}
+ */
+function discoverEccStageCommands(eccHome) {
+  const commandsDir = join(eccHome, 'commands');
+  if (!existsSync(commandsDir)) return [];
+  const entries = readdirSync(commandsDir);
+  const stageNames = [];
+  for (const entry of entries) {
+    if (extname(entry).toLowerCase() !== '.md') continue;
+    const name = basename(entry, '.md');
+    if (AW_STAGE_COMMANDS.has(name)) stageNames.push(name);
+  }
+  stageNames.sort();
+  return stageNames;
+}
+
+function harnessTargetDir(harness, home) {
+  if (harness === 'cursor-cloud') return join(home, '.cursor/commands/aw');
+  if (harness === 'codex-web') return join(home, '.codex/commands/aw');
+  return null;
+}
+
+function isCorrectSymlink(linkPath, expectedTarget) {
+  if (!existsSync(linkPath)) return false;
+  let stat;
+  try {
+    stat = lstatSync(linkPath);
+  } catch {
+    return false;
+  }
+  if (!stat.isSymbolicLink()) return false;
+  try {
+    return readlinkSync(linkPath) === expectedTarget;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Symlink one stage command from ECC into the harness command directory,
+ * replacing a stale symlink if needed. Returns true on success.
+ */
+function linkStageCommand(stageName, eccHome, targetDir) {
+  const sourcePath = join(eccHome, 'commands', `${stageName}.md`);
+  const linkPath = join(targetDir, `${stageName}.md`);
+  if (isCorrectSymlink(linkPath, sourcePath)) return true;
+  // Replace any stale symlink or wrong-type entry.
+  try {
+    if (existsSync(linkPath) || lstatExists(linkPath)) {
+      try { unlinkSync(linkPath); } catch { /* may be a directory */ }
+    }
+    symlinkSync(sourcePath, linkPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function lstatExists(p) {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure the harness slash-command surface for AW stages.
+ *
+ * @param {object} opts
+ * @param {'claude-web'|'cursor-cloud'|'codex-web'|string} opts.harness
+ * @param {string} opts.home
+ * @param {string} opts.eccHome
+ * @returns {{
+ *   harness: string,
+ *   expectedCommands: string[],
+ *   found: string[],
+ *   missing: string[],
+ *   installedAction: 'symlink' | 'noop' | 'unsupported',
+ * }}
+ */
+export function ensureCommandSurface(opts) {
+  if (!opts || typeof opts !== 'object') {
+    throw new Error('ensureCommandSurface: opts object is required');
+  }
+  const { harness, home, eccHome } = opts;
+  if (!home || typeof home !== 'string') {
+    throw new Error('ensureCommandSurface: opts.home is required');
+  }
+  if (!eccHome || typeof eccHome !== 'string') {
+    throw new Error('ensureCommandSurface: opts.eccHome is required');
+  }
+
+  const expectedCommands = discoverEccStageCommands(eccHome);
+
+  if (harness === 'claude-web') {
+    // Plugin marketplace (handled by claudePluginRegistry) exposes the same
+    // commands. We only verify resolution; a separate per-repo resolver will
+    // catch missing-marketplace cases via dumpPostInitState.
+    return {
+      harness,
+      expectedCommands,
+      found: [...expectedCommands],
+      missing: [],
+      installedAction: 'noop',
+    };
+  }
+
+  const targetDir = harnessTargetDir(harness, home);
+  if (!targetDir) {
+    return {
+      harness,
+      expectedCommands,
+      found: [],
+      missing: [],
+      installedAction: 'unsupported',
+    };
+  }
+
+  // Best-effort directory creation. If the parent path is blocked (e.g. a
+  // file already occupies the directory location), we cannot symlink and
+  // every command will surface as missing.
+  try {
+    mkdirSync(targetDir, { recursive: true });
+  } catch {
+    return {
+      harness,
+      expectedCommands,
+      found: [],
+      missing: [...expectedCommands],
+      installedAction: 'symlink',
+    };
+  }
+  // mkdirSync(recursive:true) is a no-op if a non-directory file exists at
+  // the target; we must verify the target is actually a directory now.
+  let isDir = false;
+  try {
+    isDir = lstatSync(targetDir).isDirectory();
+  } catch {
+    isDir = false;
+  }
+  if (!isDir) {
+    return {
+      harness,
+      expectedCommands,
+      found: [],
+      missing: [...expectedCommands],
+      installedAction: 'symlink',
+    };
+  }
+
+  const found = [];
+  const missing = [];
+  for (const stageName of expectedCommands) {
+    const ok = linkStageCommand(stageName, eccHome, targetDir);
+    if (ok) found.push(stageName);
+    else missing.push(stageName);
+  }
+
+  return {
+    harness,
+    expectedCommands,
+    found,
+    missing,
+    installedAction: 'symlink',
+  };
+}
+
+/**
+ * Read-only diagnostic. Walks the harness command directory and reports
+ * which AW stage commands are resolvable. Does not fix.
+ *
+ * @param {object} opts
+ * @param {'claude-web'|'cursor-cloud'|'codex-web'|string} opts.harness
+ * @param {string} opts.home
+ * @returns {{ expected: string[], found: string[], missing: string[], ok: boolean }}
+ */
+export function diagnoseCommandResolution(opts) {
+  if (!opts || typeof opts !== 'object') {
+    throw new Error('diagnoseCommandResolution: opts object is required');
+  }
+  const { harness, home } = opts;
+  if (!home || typeof home !== 'string') {
+    throw new Error('diagnoseCommandResolution: opts.home is required');
+  }
+  const expected = [...AW_STAGE_COMMANDS].sort();
+
+  if (harness === 'claude-web') {
+    // Plugin marketplace path. If a `~/.claude/commands` dir exists we
+    // honor it; otherwise we trust marketplace dispatch and report ok.
+    const claudeDir = join(home, '.claude/commands');
+    if (!existsSync(claudeDir)) {
+      return { expected, found: [], missing: [], ok: true };
+    }
+    return walkCommandsDir(claudeDir, expected);
+  }
+
+  const targetDir = harnessTargetDir(harness, home);
+  if (!targetDir) {
+    return { expected, found: [], missing: [...expected], ok: false };
+  }
+  return walkCommandsDir(targetDir, expected);
+}
+
+function walkCommandsDir(dir, expected) {
+  if (!existsSync(dir)) {
+    return { expected, found: [], missing: [...expected], ok: expected.length === 0 };
+  }
+  const present = new Set();
+  try {
+    for (const entry of readdirSync(dir)) {
+      if (extname(entry).toLowerCase() !== '.md') continue;
+      const name = basename(entry, '.md');
+      if (AW_STAGE_COMMANDS.has(name)) present.add(name);
+    }
+  } catch {
+    // Unreadable directory: treat as nothing-found.
+  }
+  const found = expected.filter((n) => present.has(n));
+  const missing = expected.filter((n) => !present.has(n));
+  return { expected, found, missing, ok: missing.length === 0 };
+}

package/c4/detect.mjs

@@ -0,0 +1,62 @@
+/**
+ * c4/detect.mjs — identify the cloud harness this VM is running inside.
+ *
+ * Returned values (canonical):
+ *   'cursor-cloud' | 'codex-web' | 'claude-web' | 'unknown'
+ *
+ * Detection signals (precedence top → bottom):
+ *   1. cursor-cloud  ← env.CURSOR_AGENT === 'true' || env.CURSOR_BACKGROUND_AGENT_ID
+ *   2. codex-web     ← env.CODEX_ENVIRONMENT === '1' || /\.codex(\/|$)/.test(cwd)
+ *   3. claude-web    ← env.CLAUDE_CODE_REMOTE === 'true' || fsProbe('/home/user/.claude')
+ *   4. unknown       ← fallback
+ *
+ * Override: env.AW_C4_HARNESS (a known harness id) wins over all signals.
+ *
+ * @typedef {'cursor-cloud' | 'codex-web' | 'claude-web' | 'unknown'} HarnessId
+ */
+
+import { existsSync } from 'node:fs';
+
+export const HARNESSES = Object.freeze(['cursor-cloud', 'codex-web', 'claude-web', 'unknown']);
+
+const CODEX_CWD_PATTERN = /\.codex(\/|$)/;
+
+function defaultFsProbe(path) {
+  try {
+    return existsSync(path);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env]   Environment to inspect (defaults to process.env)
+ * @param {(path: string) => boolean} [opts.fsProbe]  Filesystem existence probe (defaults to fs.existsSync)
+ * @param {string} [opts.cwd]              Current working directory (defaults to process.cwd())
+ * @returns {HarnessId}
+ */
+export function detectHarness({
+  env = process.env,
+  fsProbe = defaultFsProbe,
+  cwd = process.cwd(),
+} = {}) {
+  const override = env.AW_C4_HARNESS;
+  if (override && HARNESSES.includes(override)) {
+    return /** @type {HarnessId} */ (override);
+  }
+
+  if (env.CURSOR_AGENT === 'true' || env.CURSOR_BACKGROUND_AGENT_ID) {
+    return 'cursor-cloud';
+  }
+
+  if (env.CODEX_ENVIRONMENT === '1' || CODEX_CWD_PATTERN.test(cwd)) {
+    return 'codex-web';
+  }
+
+  if (env.CLAUDE_CODE_REMOTE === 'true' || fsProbe('/home/user/.claude')) {
+    return 'claude-web';
+  }
+
+  return 'unknown';
+}