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

package/commands/c4.mjs

@@ -0,0 +1,387 @@
+/**
+ * commands/c4.mjs — orchestrator for `aw c4` (cloud bootstrap).
+ *
+ * Mirrors the pilot bootstraps (`claude-web-bootstrap.sh` /
+ * `cursor-web-bootstrap.sh`) as a single 18-step Node sequence over the
+ * c4/ primitive surface. See spec.md::§"c4.mjs orchestrator contract"
+ * for the canonical list of steps and their failure modes.
+ *
+ * Two non-install modes:
+ *   --dry-run   stops before step 6 (no npm install, no aw init, no harness writes).
+ *   --diagnose  runs only steps 1, 16, 17, 18 — and ALWAYS exits 0
+ *               (G7: report mode, not gate mode).
+ *
+ * Every barrel symbol used here is dependency-injected via the second
+ * argument so the test in tests/c4/c4.command.test.mjs can exercise the
+ * decision branches without spawning real subprocesses, touching the
+ * real filesystem, or hitting the real network. The default deps come
+ * from c4/index.mjs (the production wiring).
+ *
+ * Contract: spec.md::§"c4.mjs orchestrator contract", tasks.md::4.4.
+ */
+
+import { spawnSync as nodeSpawnSync } from 'node:child_process';
+import { existsSync as fsExistsSync } from 'node:fs';
+import { join } from 'node:path';
+import * as c4Default from '../c4/index.mjs';
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Constants — referenced by self-tests.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+const MIN_VIEWABLE_STAGE_SKILLS = 3;
+const SUPPORTED_HARNESSES = ['cursor-cloud', 'codex-web', 'claude-web', 'unknown'];
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Argument parsing — shared by Cli wrapper and direct callers.
+ *
+ * `args` may arrive either as the cli.mjs-parsed object (`{ '--dry-run': true,
+ * '--harness': 'codex-web', ... }`) or as a plain `string[]`. Normalize.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+function normalizeArgs(input) {
+  if (Array.isArray(input)) {
+    const out = { _positional: [] };
+    for (let i = 0; i < input.length; i++) {
+      const a = input[i];
+      if (a === '--dry-run' || a === '-v' || a === '--verbose' || a === '--diagnose' || a === '--skip-pull') {
+        out[a] = true;
+      } else if (a === '--harness') {
+        out['--harness'] = input[i + 1];
+        i++;
+      } else if (a.startsWith('--')) {
+        out[a] = true;
+      } else {
+        out._positional.push(a);
+      }
+    }
+    return out;
+  }
+  return input ?? {};
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * IO defaults — easy to override in tests.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+const DEFAULT_WRITER = {
+  stdout: (s) => process.stdout.write(s),
+  stderr: (s) => process.stderr.write(s),
+};
+
+function defaultExit(code) {
+  process.exit(code);
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Helpers — pure utility, no orchestration state.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+function safe(label, fn, writer) {
+  try {
+    return { ok: true, value: fn() };
+  } catch (err) {
+    writer.stderr(`[aw-c4] ${label} failed (non-fatal): ${err?.message ?? err}\n`);
+    return { ok: false, error: err };
+  }
+}
+
+async function safeAsync(label, fn, writer) {
+  try {
+    return { ok: true, value: await fn() };
+  } catch (err) {
+    writer.stderr(`[aw-c4] ${label} failed (non-fatal): ${err?.message ?? err}\n`);
+    return { ok: false, error: err };
+  }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * 6-step git auth subroutine (step 4 + step 8).
+ * ───────────────────────────────────────────────────────────────────────── */
+
+function setupGitAuth({ token, c4, home, cwd }) {
+  c4.clearAllGitHubAuthState({ home });
+  c4.installPatInsteadOf(token);
+  c4.installCredentialHelperStore(token, home);
+  c4.ghAuthLoginWithToken(token);
+  c4.ghAuthSetupGit();
+  c4.ensureOriginRemote({ cwd });
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Per-harness branch (step 10).
+ *
+ * Returns `{ ok, bridge, injector }` so the summary line can pick up
+ * codex-specific status ticks. Hard failures (bridge / injector / claude
+ * marketplace / slim card) bubble up as thrown Errors.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+function runHarnessBranch({ harness, c4, home, eccHome, cwd, writer }) {
+  if (harness === 'claude-web') {
+    // Marketplace registration is non-fatal — the slim card is the routing
+    // mechanism (state.json::resolved_decisions exit-code item 3 lists slim
+    // card only); marketplace failure must not exit 1.
+    safe('ensureClaudeMarketplace', () => c4.ensureClaudeMarketplace(home, eccHome), writer);
+    c4.installSlimRouter('claude-web', home);
+    safe('ensureRepoLocalClaudeSettings', () => c4.ensureRepoLocalClaudeSettings(cwd), writer);
+    return { ok: true };
+  }
+  if (harness === 'cursor-cloud' || harness === 'unknown') {
+    // Treat unknown as cursor-cloud (per spec.md::§"Harness detect"): the
+    // slim card with Read-syntax is the safe fallback for unrecognized
+    // harnesses.
+    c4.installSlimRouter('cursor-cloud', home);
+    return { ok: true };
+  }
+  if (harness === 'codex-web') {
+    const awHome = join(home, '.aw');
+    c4.applyEccRegistryBridge({ awHome, eccHome });
+    c4.ensureCodexHooksFlag(home);
+    const routerSkillPath = join(awHome, '.aw_registry/platform/core/skills/using-aw-skills/SKILL.md');
+    // Pass hookPath explicitly: defaultHookPath() reads os.homedir() at module
+    // load time, which ignores the orchestrator's `home` (env.HOME). Without
+    // this, installs land in the real ~/.codex even when HOME is overridden
+    // (caught by tests/c4/c4.smoke.test.mjs::"codex-web happy path").
+    const hookPath = join(home, '.codex/hooks/aw-user-prompt-submit.sh');
+    c4.installCodexPromptInjector({ hookPath, routerSkillPath });
+    return { ok: true, bridge: { ok: true }, injector: { ok: true } };
+  }
+  throw new Error(`unknown harness: ${harness}`);
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Self-tests (step 16). Returns { ok, failures: string[] }.
+ *
+ * In install mode the orchestrator exits 1 on `ok=false`. In diagnose mode
+ * the report is always emitted and the exit is forced to 0.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+function runSelfTests({ harness, c4, home, awHome, eccHome }) {
+  const failures = [];
+
+  const skill = c4.diagnoseSkillResolution({ harness, home, awHome, eccHome });
+  if (!skill.ok) failures.push('skill-resolution');
+
+  // diagnoseCommandResolution is warn-only — does NOT add to failures.
+  const command = c4.diagnoseCommandResolution({ harness, home });
+
+  let view;
+  let injector;
+  if (harness === 'codex-web') {
+    view = c4.diagnoseAwRouterView({ awHome });
+    if (view.enumerableSkills.length < MIN_VIEWABLE_STAGE_SKILLS) failures.push('aw-router-view');
+    injector = c4.diagnosePromptRouterInjection(home, { simulateFirstTurn: true });
+    if (!injector.ok) failures.push('prompt-injector');
+  }
+
+  return { ok: failures.length === 0, failures, skill, command, view, injector };
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * c4Command — public entrypoint.
+ *
+ * The second argument is for tests + advanced callers; production usage
+ * goes through cli.mjs which calls `c4Command(args)` (one-arg form) and
+ * the defaults take over.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+/**
+ * @param {object|string[]} rawArgs
+ * @param {object} [overrides]
+ * @param {object} [overrides.c4]        Override the entire c4 barrel.
+ * @param {Function} [overrides.spawnSync]
+ * @param {object} [overrides.fs]        `{ existsSync }` shape.
+ * @param {object} [overrides.writer]    `{ stdout, stderr }` write fns.
+ * @param {Function} [overrides.exit]
+ * @param {NodeJS.ProcessEnv} [overrides.env]
+ * @param {string} [overrides.cwd]
+ * @param {Function} [overrides.now]     Returns ms epoch — for deterministic durations in tests.
+ */
+export async function c4Command(rawArgs, overrides = {}) {
+  const args = normalizeArgs(rawArgs);
+  const c4 = overrides.c4 ?? c4Default;
+  const spawnSync = overrides.spawnSync ?? nodeSpawnSync;
+  const fs = overrides.fs ?? { existsSync: fsExistsSync };
+  const writer = overrides.writer ?? DEFAULT_WRITER;
+  const exit = overrides.exit ?? defaultExit;
+  const env = overrides.env ?? process.env;
+  const cwd = overrides.cwd ?? process.cwd();
+  const now = overrides.now ?? (() => Date.now());
+
+  const startTs = now();
+
+  // Step 1 — harness detection (override wins).
+  const cliHarness = args['--harness'];
+  const harness = SUPPORTED_HARNESSES.includes(cliHarness) ? cliHarness : c4.detectHarness({ env }).harness;
+  const home = env.HOME ?? '~';
+  const awHome = join(home, '.aw');
+  const awRegistry = join(awHome, '.aw_registry');
+  const eccHome = join(home, '.aw-ecc');
+
+  // Step 2 — token resolution.
+  const { token, source: tokenSource } = c4.getGithubToken(env);
+  if (!token) {
+    writer.stdout(c4.summarizeAsOneLine({
+      harness,
+      hasToken: false,
+      tokenSource: null,
+      authOk: false,
+      didInit: false,
+      durationMs: now() - startTs,
+    }) + '\n');
+    return exit(0);
+  }
+
+  // --diagnose: skip ahead to self-tests + dump + summary.
+  // G7 contract — ALWAYS exit 0, even on unexpected throws inside the
+  // diagnostic probes. The whole branch body is wrapped in try/catch so a
+  // throw from runSelfTests / dumpPostInitState / summarizeAsOneLine does
+  // not leak as a process-level non-zero exit.
+  if (args['--diagnose']) {
+    let self = {
+      ok: false,
+      failures: ['diagnose-error'],
+      skill: null,
+      command: null,
+      view: undefined,
+      injector: undefined,
+    };
+    try {
+      self = runSelfTests({ harness, c4, home, awHome, eccHome });
+      c4.dumpPostInitState({ harness, cwd, awHome, configPaths: [] });
+    } catch (err) {
+      writer.stderr(`[aw-c4] diagnose: unexpected error: ${err?.message ?? err}\n`);
+    }
+    try {
+      writer.stdout(c4.summarizeAsOneLine({
+        harness,
+        hasToken: true,
+        tokenSource,
+        authOk: null, // diagnose does not probe auth — null avoids the misleading "GITHUB_PAT ✗" tick.
+        didInit: false,
+        durationMs: now() - startTs,
+        bridge: self.view ? { ok: self.view.ok } : undefined,
+        injector: self.injector ? { ok: self.injector.ok } : undefined,
+        diagnose: true,
+      }) + '\n');
+    } catch (err) {
+      writer.stderr(`[aw-c4] diagnose: summary line failed: ${err?.message ?? err}\n`);
+    }
+    if (!self.ok) {
+      writer.stderr(`[aw-c4] diagnose: failures = ${self.failures.join(', ')}\n`);
+    }
+    return exit(0); // G7: --diagnose ALWAYS exits 0.
+  }
+
+  // Step 3 — gh CLI.
+  safe('ensureGhCli', () => c4.ensureGhCli(), writer);
+
+  // Step 4 — 6-step git auth.
+  safe('setupGitAuth', () => setupGitAuth({ token, c4, home, cwd }), writer);
+
+  // Step 5 — preflight.
+  const preflight = await c4.preflightPlatformDocs(token);
+  if (preflight.diagnosis === 'pat-invalid') {
+    writer.stderr('[aw-c4] PAT invalid (REST 4xx). Refresh GITHUB_PAT and retry.\n');
+    writer.stdout(c4.summarizeAsOneLine({
+      harness,
+      hasToken: true,
+      tokenSource,
+      authOk: false,
+      didInit: false,
+      durationMs: now() - startTs,
+    }) + '\n');
+    return exit(0);
+  }
+  if (preflight.diagnosis !== 'ok') {
+    writer.stderr(`[aw-c4] preflight diagnosis: ${preflight.diagnosis} (continuing)\n`);
+  }
+
+  // --dry-run: stop before any install side effect.
+  if (args['--dry-run']) {
+    writer.stdout(c4.summarizeAsOneLine({
+      harness,
+      hasToken: true,
+      tokenSource,
+      authOk: preflight.diagnosis === 'ok',
+      didInit: false,
+      durationMs: now() - startTs,
+    }) + '\n');
+    return exit(0);
+  }
+
+  // Step 6 — npm install -g @ghl-ai/aw.
+  const npmRes = spawnSync('npm', ['install', '-g', '@ghl-ai/aw'], { stdio: 'pipe' });
+  if (npmRes && npmRes.status !== 0) {
+    writer.stderr('[aw-c4] npm install -g @ghl-ai/aw failed (non-fatal); using existing aw if present\n');
+  }
+
+  // Step 7 — aw init --silent.
+  const initRes = spawnSync('aw', ['init', '--silent'], { stdio: 'pipe' });
+  if (initRes && initRes.status !== 0) {
+    writer.stderr('[aw-c4] aw init failed; ECC verification will catch any missing artefacts\n');
+  }
+
+  // Step 8 — re-apply git auth post-init.
+  safe('setupGitAuth(post-init)', () => setupGitAuth({ token, c4, home, cwd }), writer);
+
+  // Step 9 — verify ECC + registry provisioned.
+  if (!fs.existsSync(eccHome) || !fs.existsSync(awRegistry)) {
+    writer.stderr('[aw-c4] FATAL: aw init did not provision ~/.aw-ecc or ~/.aw/.aw_registry\n');
+    return exit(1);
+  }
+
+  // Step 10 — per-harness branch.
+  let branch;
+  try {
+    branch = runHarnessBranch({ harness, c4, home, eccHome, cwd, writer });
+  } catch (err) {
+    writer.stderr(`[aw-c4] FATAL: harness branch (${harness}) failed: ${err?.message ?? err}\n`);
+    return exit(1);
+  }
+
+  // Step 11 — MCP register.
+  safe('registerGhlAiMcp', () => c4.registerGhlAiMcp(harness, home, token), writer);
+
+  // Step 12 — slash command surface.
+  safe('ensureCommandSurface', () => c4.ensureCommandSurface({ harness, home, eccHome }), writer);
+
+  // Step 13 — repo-root context.
+  safe('copyRepoRootInstructions', () => c4.copyRepoRootInstructions(harness, cwd, eccHome), writer);
+
+  // Step 14 — repo-local ignore.
+  safe('ensureRepoLocalIgnore', () => c4.ensureRepoLocalIgnore({ cwd, harness }), writer);
+
+  // Step 15 — MCP smoke probe (best-effort).
+  const mcpProbe = await safeAsync(
+    'probeMcpServer',
+    () => c4.probeMcpServer({ url: c4.MCP_URL_DEFAULT, token }),
+    writer,
+  );
+
+  // Step 16 — self-tests.
+  const self = runSelfTests({ harness, c4, home, awHome, eccHome });
+  if (!self.ok) {
+    writer.stderr(`[aw-c4] FATAL: self-tests failed: ${self.failures.join(', ')}\n`);
+    c4.dumpPostInitState({ harness, cwd, awHome, configPaths: [] });
+    return exit(1);
+  }
+
+  // Step 17 — post-init dump.
+  c4.dumpPostInitState({ harness, cwd, awHome, configPaths: [] });
+
+  // Step 18 — one-line summary.
+  writer.stdout(c4.summarizeAsOneLine({
+    harness,
+    hasToken: true,
+    tokenSource,
+    authOk: preflight.diagnosis === 'ok',
+    didInit: true,
+    durationMs: now() - startTs,
+    bridge: branch?.bridge,
+    injector: branch?.injector,
+    mcpProbe: mcpProbe?.value?.authStatus,
+  }) + '\n');
+
+  return exit(0);
+}

package/ecc.mjs

@@ -10,9 +10,9 @@ import { homedir } from "node:os";
 import * as fmt from "./fmt.mjs";
 import { applyStoredStartupPreferences } from "./startup.mjs";
 
-const AW_ECC_REPO_SSH = "git@github.com:GoHighLevel/aw-ecc.git";
-const AW_ECC_REPO_HTTPS = "https://github.com/GoHighLevel/aw-ecc.git";
-export const AW_ECC_TAG = "v1.4.45";
+const AW_ECC_REPO_SSH = "git@github.com:shreyansh-ghl/aw-ecc.git";
+const AW_ECC_REPO_HTTPS = "https://github.com/shreyansh-ghl/aw-ecc.git";
+export const AW_ECC_TAG = "v1.4.43";
 
 const MARKETPLACE_NAME = "aw-marketplace";
 const PLUGIN_KEY = `aw@${MARKETPLACE_NAME}`;
@@ -475,75 +475,10 @@ export function uninstallAwEcc({ silent = false } = {}) {
     } catch { /* best effort */ }
   }
 
-  // Clean leftover plugin cache directories (Claude Code may not fully remove these)
-  for (const cacheName of ["aw", "aw-marketplace"]) {
-    const cacheDir = join(HOME, ".claude", "plugins", "cache", cacheName);
-    if (existsSync(cacheDir)) {
-      try { rmSync(cacheDir, { recursive: true, force: true }); removed++; } catch { /* best effort */ }
-    }
-  }
-
-  // Clean rules copied by session-start hook (plugin-only users)
-  const pluginRulesDir = join(HOME, ".claude", "rules", "platform");
-  if (existsSync(pluginRulesDir)) {
-    try { rmSync(pluginRulesDir, { recursive: true, force: true }); removed++; } catch { /* best effort */ }
-  }
-
-  // Clean commands created by docsregistry sync (all IDEs)
-  for (const cmdDir of [
-    join(HOME, ".claude", "commands", "aw"),
-    join(HOME, ".cursor", "commands", "aw"),
-  ]) {
-    if (existsSync(cmdDir)) {
-      try { rmSync(cmdDir, { recursive: true, force: true }); removed++; } catch { /* best effort */ }
-    }
-  }
-
-  // Strip aw-managed content from ~/.claude/CLAUDE.md (keep user content above the marker)
-  const claudeMdPath = join(HOME, ".claude", "CLAUDE.md");
-  if (existsSync(claudeMdPath)) {
-    try {
-      const content = readFileSync(claudeMdPath, "utf8");
-      const marker = "<!-- aw-managed:";
-      const idx = content.indexOf(marker);
-      if (idx !== -1) {
-        const userContent = content.slice(0, idx).trimEnd();
-        if (userContent.length > 0) {
-          writeFileSync(claudeMdPath, userContent + "\n");
-        } else {
-          rmSync(claudeMdPath, { force: true });
-        }
-        removed++;
-      }
-    } catch { /* best effort */ }
-  }
-
-  // Clean Codex aw hooks
-  const codexHooksDir = join(HOME, ".codex", "hooks");
-  if (existsSync(codexHooksDir)) {
-    try {
-      for (const file of readdirSync(codexHooksDir)) {
-        if (file.startsWith("aw-") || file.startsWith("session-end-extract") || file.startsWith("session-stop-marker")) {
-          rmSync(join(codexHooksDir, file), { force: true });
-          removed++;
-        }
-      }
-      pruneEmptyParents(codexHooksDir, join(HOME, ".codex"));
-    } catch { /* best effort */ }
-  }
-
-  // Clean Codex ecc backup directories
-  const codexBackupsDir = join(HOME, ".codex", "backups");
-  if (existsSync(codexBackupsDir)) {
-    try {
-      for (const dir of readdirSync(codexBackupsDir)) {
-        if (dir.startsWith("ecc-")) {
-          rmSync(join(codexBackupsDir, dir), { recursive: true, force: true });
-          removed++;
-        }
-      }
-      pruneEmptyParents(codexBackupsDir, join(HOME, ".codex"));
-    } catch { /* best effort */ }
+  // Clean leftover manual plugin cache from older versions
+  const oldCache = join(HOME, ".claude", "plugins", "cache", "aw");
+  if (existsSync(oldCache)) {
+    try { rmSync(oldCache, { recursive: true, force: true }); removed++; } catch { /* best effort */ }
   }
 
   // Remove permanent aw-ecc repo clone — use rm -rf (more reliable than rmSync on git repos)

package/integrate.mjs

@@ -19,7 +19,7 @@ const AW_ROUTER_BRIDGE_END_MARKER = '<!-- aw-managed:end router-bridge -->';
 const AGENTS_RULES_HEADER = 'Platform Rules — Non-Negotiables';
 const CLAUDE_RULES_HEADER = 'Platform Rules (MUST)';
 
-function generateAwRouterBridgeSection() {
+export function generateAwRouterBridgeSection() {
   return `${AW_ROUTER_BRIDGE_START_MARKER}
 ## ${AW_ROUTER_BRIDGE_HEADER}
 
@@ -38,11 +38,11 @@ function generateAwRouterBridgeSection() {
 - For non-trivial work, inspect platform docs, runtime behavior, app surfaces, and integration boundaries first
 - Ask one short clarifying question only when ambiguity remains after exploration
 
-### 4. Build in Small Steps
-- For multi-step work, resolve and apply \`incremental-implementation\`
-- Break work into thin, reversible slices with validation at each step
-- Prefer extending existing patterns over inventing new ones
-- Never batch unrelated changes in one pass
+### 4. Route New Work via /aw:plan
+- For new endpoints, services, schemas, integrations, multi-file changes, or unclear scope, route via \`/aw:plan\` before writing code
+- Do not jump to \`incremental-implementation\` (or any cross-cutting skill) without first selecting the AW stage skill via \`using-aw-skills\`
+- Cross-cutting skills are loaded by the stage skill when the stage skill calls for them, not directly
+- Break work into thin reversible slices once the stage skill is chosen
 
 ### 5. Verify With Proof
 - For bug fixes and behavior changes, use Red -> Green -> Refactor

package/mcp.mjs

@@ -249,7 +249,6 @@ async function resolveClickUpToken(silent = false, cwd = process.cwd()) {
   return token;
 }
 
-
 /**
  * Setup MCP configs globally for Claude Code and Cursor.
  * Merges ghl-ai server into existing configs without overwriting other servers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.44-beta.1",
+  "version": "0.1.44-beta.2",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "bin.js",
+    "c4/",
     "cli.mjs",
     "commands/",
     "config.mjs",
@@ -50,9 +51,9 @@
   "license": "MIT",
   "scripts": {
     "test": "yarn test:vitest && yarn test:node",
-    "test:vitest": "vitest run --reporter=verbose tests/commands tests/mcp.test.mjs tests/telemetry.test.mjs",
+    "test:vitest": "vitest run --reporter=verbose tests/commands tests/mcp.test.mjs tests/telemetry.test.mjs tests/c4",
     "test:node": "node tests/run-node-tests.mjs",
-    "test:watch": "vitest --reporter=verbose tests/commands tests/mcp.test.mjs tests/telemetry.test.mjs",
+    "test:watch": "vitest --reporter=verbose tests/commands tests/mcp.test.mjs tests/telemetry.test.mjs tests/c4",
     "preuninstall": "node bin.js nuke 2>/dev/null || true"
   },
   "publishConfig": {
@@ -60,6 +61,7 @@
   },
   "dependencies": {
     "@clack/prompts": "0.8.2",
+    "@iarna/toml": "^2.2.5",
     "chalk": "^5.6.2",
     "figlet": "^1.11.0",
     "pg": "^8.13.0"