@ghl-ai/aw 0.1.44-beta.10 → 0.1.44-beta.12

package/c4/initRepo.mjs

@@ -23,9 +23,127 @@ import {
   chmodSync,
   statSync,
 } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, basename, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Default `git check-ignore` runner. Returns true when `relpath` is ignored
+ * by the user's gitignore rules, false otherwise (or when git is unavailable).
+ *
+ * Exit codes per `git check-ignore --quiet`:
+ *   0 — file IS ignored
+ *   1 — file is NOT ignored
+ *   128 — error (no git repo, etc.) — treat as not-ignored to avoid noisy
+ *         false-positive warnings on broken installs
+ */
+const DEFAULT_CHECK_IGNORE = (repoRoot, relpath) => {
+  try {
+    const result = spawnSync(
+      'git',
+      ['-C', repoRoot, 'check-ignore', '--quiet', relpath],
+      { stdio: 'pipe' },
+    );
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Variable substitution table for `kind: "interpolated"` templates.
+ *
+ * Each value is computed lazily from `opts` (the engine call site provides
+ * `repoRoot`). Adding a new variable here means it becomes referenceable as
+ * `{{NAME}}` inside any interpolated template.
+ *
+ * REPO_BASENAME is the leaf directory name of `repoRoot` after `path.resolve`
+ * — exactly what Codex Cloud uses as the project key (`/workspace/<basename>`).
+ */
+const SUBSTITUTIONS = {
+  REPO_BASENAME: (opts) => basename(resolve(opts.repoRoot)),
+};
+
+/**
+ * Render `{{VAR}}` placeholders in `content` using the SUBSTITUTIONS table.
+ *
+ * Throws on any `{{...}}` reference whose key isn't in the table — fail loud
+ * over silently shipping `{{REPO_BASENAME}}` in a config file.
+ *
+ * @param {string} content
+ * @param {{repoRoot: string}} opts
+ * @returns {string} content with all known placeholders substituted
+ */
+function renderInterpolated(content, opts) {
+  return content.replace(/\{\{(\w+)\}\}/g, (_, name) => {
+    if (!Object.prototype.hasOwnProperty.call(SUBSTITUTIONS, name)) {
+      throw new Error(
+        `init-repo: unknown variable {{${name}}} in interpolated template. ` +
+        `Known: ${Object.keys(SUBSTITUTIONS).join(', ')}.`,
+      );
+    }
+    return SUBSTITUTIONS[name](opts);
+  });
+}
+
+/**
+ * Render the full expected file content for a `kind: "managed-block"` template.
+ *
+ * Reads the bundled block source (just the inner lines), strips any existing
+ * managed block bearing the same `marker` from the dest file (so re-runs
+ * cleanly replace stale content), and appends a fresh marker-wrapped block.
+ *
+ * Format on disk (matches existing AW convention from integrate.mjs and
+ * repoRootInstructions.mjs — colon-no-space, marker name on both ends):
+ *   <pre-existing user content (managed block stripped)>
+ *
+ *   # aw-managed:start <marker> (DO NOT EDIT — managed by `aw init-repo`)
+ *   <block source content>
+ *   # aw-managed:end <marker>
+ *
+ * The single blank line separator between user content and our block is only
+ * emitted when prior content exists. The file always ends with one trailing
+ * newline.
+ *
+ * @param {{src: string, marker: string}} template
+ * @param {{templatesDir: string, repoRoot: string}} opts
+ * @returns {string} full expected file content
+ */
+function renderManagedBlock(template, opts) {
+  const blockSrcPath = join(opts.templatesDir, template.src);
+  const blockBody = readFileSync(blockSrcPath, 'utf8').replace(/\n+$/, '');
+
+  const destPath = join(opts.repoRoot, template.dest);
+  const existing = existsSync(destPath) ? readFileSync(destPath, 'utf8') : '';
+  const preserved = stripManagedBlock(existing, template.marker).replace(/\n+$/, '');
+
+  const wrapped =
+    `# aw-managed:start ${template.marker} (DO NOT EDIT — managed by \`aw init-repo\`)\n` +
+    blockBody +
+    '\n' +
+    `# aw-managed:end ${template.marker}\n`;
+
+  return preserved.length > 0 ? `${preserved}\n\n${wrapped}` : wrapped;
+}
+
+/**
+ * Remove every `# aw-managed:start <marker> ... # aw-managed:end <marker>`
+ * block from `content`. Idempotent on content with no such block.
+ *
+ * Defensive against multiple stale blocks with the same marker (all collapse
+ * to none — fresh block is appended afterward by the caller).
+ */
+function stripManagedBlock(content, marker) {
+  const safeMarker = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(
+    `(?:^|\\n)# aw-managed:start ${safeMarker}(?:[^\\n]*)\\n` +
+    `[\\s\\S]*?` +
+    `# aw-managed:end ${safeMarker}[ \\t]*\\n?`,
+    'g',
+  );
+  return content.replace(re, '\n');
+}
 
 /** Default fs surface — node:fs. Tests inject mocks for failure paths. */
 const DEFAULT_FS = {
@@ -88,19 +206,40 @@ export function loadManifest(templatesDir) {
 }
 
 /**
- * Read the bundled template content for a single manifest entry.
+ * Render the expected file content for a single manifest entry.
+ *
+ * Dispatch by `template.kind`:
+ *   - 'literal'        → readFileSync of the bundled src verbatim
+ *   - 'interpolated'   → readFileSync + {{VAR}} substitution via SUBSTITUTIONS
+ *   - 'managed-block'  → strip stale managed block from dest, append fresh
+ *                        marker-wrapped block built from src body. Returns the
+ *                        FULL rendered dest content (preserves user content
+ *                        outside the markers).
  *
- * Pure read — no FS writes. Pulled out of planActions so tests can
- * exercise it directly and so the action object can carry both
- * expected and current content for downstream diff/overwrite decisions.
+ * Pure read — no FS writes. Tests can exercise this directly. The action
+ * object carries both expected and current content so applyActions and the
+ * diff renderer don't have to re-read.
  *
- * @param {{src: string}} template manifest entry
- * @param {{templatesDir: string}} opts engine options
- * @returns {string} bundled template content (UTF-8)
+ * @param {{kind?: string, src: string, dest?: string, marker?: string}} template
+ * @param {{templatesDir: string, repoRoot?: string}} opts
+ * @returns {string} rendered template content (UTF-8)
  */
 export function expectedContent(template, opts) {
-  const srcPath = join(opts.templatesDir, template.src);
-  return readFileSync(srcPath, 'utf8');
+  const kind = template.kind ?? 'literal';
+
+  if (kind === 'literal') {
+    return readFileSync(join(opts.templatesDir, template.src), 'utf8');
+  }
+  if (kind === 'interpolated') {
+    const raw = readFileSync(join(opts.templatesDir, template.src), 'utf8');
+    return renderInterpolated(raw, opts);
+  }
+  if (kind === 'managed-block') {
+    return renderManagedBlock(template, opts);
+  }
+  throw new Error(
+    `init-repo: unknown template kind "${kind}" for ${template.src ?? '?'}.`,
+  );
 }
 
 /**
@@ -159,7 +298,12 @@ export function planActions(opts, manifest) {
     }
 
     let action;
-    if (opts.diff) {
+    if (template.kind === 'managed-block') {
+      // We own the marker-bracketed area; user edits OUTSIDE the markers are
+      // preserved by renderManagedBlock. Mismatch always means "our block is
+      // stale or missing" → safe to overwrite.
+      action = 'overwrite';
+    } else if (opts.diff) {
       action = 'diff';
     } else if (opts.force) {
       action = 'overwrite';
@@ -206,17 +350,75 @@ export function applyActions(opts, actions) {
     fs.mkdirSync(dirname(action.dest), { recursive: true });
     fs.writeFileSync(action.dest, action.expectedContent);
 
-    try {
-      fs.chmodSync(action.dest, parseInt(action.template.mode, 8));
-    } catch (err) {
-      writer.stderr(
-        `init-repo: WARN: failed to chmod ${action.dest}: ${err.code ?? err.message}. ` +
-        `File written but executable bit may be missing — set manually with chmod +x ${action.dest}.\n`,
-      );
+    if (action.template.mode) {
+      try {
+        fs.chmodSync(action.dest, parseInt(action.template.mode, 8));
+      } catch (err) {
+        writer.stderr(
+          `init-repo: WARN: failed to chmod ${action.dest}: ${err.code ?? err.message}. ` +
+          `File written but executable bit may be missing — set manually with chmod +x ${action.dest}.\n`,
+        );
+      }
     }
   }
 }
 
+/**
+ * Run `git check-ignore` against every scaffolded file and return the list
+ * of paths still ignored after applyActions wrote the managed `.gitignore`
+ * block. Surfaces pathological gitignore patterns we can't override (most
+ * notably dir-only rules like `.codex/` — git refuses to look inside an
+ * excluded directory regardless of subsequent `!` rules).
+ *
+ * Skips:
+ *   - managed-block kind (`.gitignore` itself isn't normally tracked)
+ *   - blocked-edited / diff actions (file content is user's, not ours)
+ *
+ * @param {{repoRoot: string, checkIgnore?: (root: string, p: string) => boolean}} opts
+ * @param {Array} actions
+ * @returns {string[]} list of dest paths still ignored
+ */
+function verifyIgnoreStatus(opts, actions) {
+  const checkIgnore = opts.checkIgnore ?? DEFAULT_CHECK_IGNORE;
+  const stillIgnored = [];
+
+  for (const action of actions) {
+    if (action.template.kind === 'managed-block') continue;
+    if (action.action === 'blocked-edited' || action.action === 'diff') continue;
+
+    if (checkIgnore(opts.repoRoot, action.template.dest)) {
+      stillIgnored.push(action.template.dest);
+    }
+  }
+  return stillIgnored;
+}
+
+/**
+ * Build a stderr WARNING block for paths still ignored after applyActions.
+ *
+ * Most common cause: dir-only patterns (`.codex/`, `.claude/`) — git docs
+ * explicitly forbid re-include of files under an excluded directory. The
+ * fix is user-side, so we surface the exact paths and the change they need.
+ */
+function buildIgnoreWarning(paths) {
+  return [
+    '',
+    `init-repo: WARN: ${paths.length} scaffolded file${paths.length === 1 ? '' : 's'} still git-ignored:`,
+    ...paths.map((p) => `   - ${p}`),
+    '',
+    'Your .gitignore has rules that block our managed re-include — most likely',
+    'dir-only patterns (e.g. `.codex/`, `.claude/`, `.cursor/`). Per gitignore',
+    'docs, files cannot be re-included once a parent directory is excluded.',
+    '',
+    'Fix: change those rules to use a trailing `*` so they ignore CONTENTS rather',
+    'than the directory itself, then re-run `aw init-repo`. Examples:',
+    '   .codex/    →   .codex/*',
+    '   .claude/   →   .claude/*',
+    '   .cursor/   →   .cursor/*',
+    '',
+  ].join('\n');
+}
+
 /**
  * Format a single action line for the summary block.
  *
@@ -275,6 +477,8 @@ function buildSummary({ repoRoot, dryRun, actions, blockedCount, exitCode }) {
  *   force?: boolean,
  *   diff?: boolean,
  *   dryRun?: boolean,
+ *   noGitignore?: boolean,
+ *   checkIgnore?: (root: string, p: string) => boolean,
  *   fs?: object,
  *   writer?: object,
  * }} opts
@@ -315,9 +519,16 @@ export function initRepo(opts) {
     return { exitCode: 2, summary: err.message, actions: [] };
   }
 
+  // --no-gitignore opt-out: drop every managed-block template before planning.
+  // Users who manage their .gitignore by hand can pass this flag to keep
+  // init-repo from injecting the cloud-bootstrap re-include block.
+  const filteredManifest = opts.noGitignore
+    ? { ...manifest, templates: manifest.templates.filter(t => t.kind !== 'managed-block') }
+    : manifest;
+
   const actions = planActions(
     { repoRoot, templatesDir, force: opts.force, diff: opts.diff, fs },
-    manifest,
+    filteredManifest,
   );
 
   applyActions(
@@ -338,5 +549,19 @@ export function initRepo(opts) {
 
   writer.stdout(summary + '\n');
 
+  // Post-apply: verify that scaffolded paths are actually trackable by git.
+  // Emitted AFTER the summary so the action list always renders first
+  // regardless of stdout/stderr buffering. Skip on dryRun — nothing was
+  // written, so check-ignore would probe stale state and emit noise.
+  if (!opts.dryRun) {
+    const stillIgnored = verifyIgnoreStatus(
+      { repoRoot, checkIgnore: opts.checkIgnore },
+      actions,
+    );
+    if (stillIgnored.length > 0) {
+      writer.stderr(buildIgnoreWarning(stillIgnored) + '\n');
+    }
+  }
+
   return { exitCode, summary, actions };
 }

package/c4/templates/codex/config.toml

@@ -0,0 +1,5 @@
+[features]
+codex_hooks = true
+
+[projects."/workspace/{{REPO_BASENAME}}"]
+trust_level = "trusted"

package/c4/templates/gitignore-block.txt

@@ -0,0 +1,14 @@
+# Cloud bootstrap files — re-include for tracking even when parent dirs are
+# ignored (e.g. .codex/*, .claude/*, .cursor/*). Order matters: a file under
+# an excluded directory cannot be un-ignored without first un-ignoring the
+# directory. We only un-ignore parent paths and whitelist AW-managed files —
+# we do NOT re-ignore other content inside these dirs, so users' own scripts
+# stay trackable. Hook-logs and other ephemeral state are managed elsewhere
+# (see `aw init`'s repoLocalIgnore manager).
+!scripts/aw-c4-bootstrap.sh
+!.codex/config.toml
+!.cursor/environment.json
+!.codex/scripts/
+!.codex/scripts/codex-web-bootstrap.sh
+!.claude/scripts/
+!.claude/scripts/claude-web-bootstrap.sh

package/c4/templates/manifest.json

@@ -24,6 +24,18 @@
       "src": "cursor/environment.json",
       "dest": ".cursor/environment.json",
       "mode": "0644"
+    },
+    {
+      "kind": "interpolated",
+      "src": "codex/config.toml",
+      "dest": ".codex/config.toml",
+      "mode": "0644"
+    },
+    {
+      "kind": "managed-block",
+      "src": "gitignore-block.txt",
+      "dest": ".gitignore",
+      "marker": "cloud-bootstrap"
     }
   ]
 }

package/commands/init-repo.mjs

@@ -16,16 +16,19 @@ const HELP = `
 aw init-repo — scaffold cloud-bootstrap files into the current repo
 
 Usage:
-  aw init-repo                Scaffold 4 files (idempotent: skip-equal on byte match)
-  aw init-repo --dry-run      Preview actions without writing
-  aw init-repo --diff         Show diffs for locally-edited files (no write)
-  aw init-repo --force        Overwrite locally-edited files
+  aw init-repo                  Scaffold 6 files (idempotent: skip-equal on byte match)
+  aw init-repo --dry-run        Preview actions without writing
+  aw init-repo --diff           Show diffs for locally-edited files (no write)
+  aw init-repo --force          Overwrite locally-edited files
+  aw init-repo --no-gitignore   Skip the .gitignore managed block (manage it by hand)
 
 Files written:
-  scripts/aw-c4-bootstrap.sh                  (4.4 KB, executable)
+  scripts/aw-c4-bootstrap.sh                  (unified bootstrap, executable)
   .codex/scripts/codex-web-bootstrap.sh       (executable)
+  .codex/config.toml                          (codex hooks + per-repo trust)
   .claude/scripts/claude-web-bootstrap.sh     (executable)
   .cursor/environment.json                    (cursor cloud config)
+  .gitignore                                  (managed block — re-include of the 5 above)
 
 Exit codes:
   0  All files created or already in sync
@@ -35,8 +38,15 @@ Exit codes:
 Notes:
   - Idempotent. SHA-256 byte-compare per file. Re-running on a clean repo is a no-op.
   - --namespace is NOT supported (use 'aw init --namespace <team>' for namespace pulls).
-  - .cursor/environment.json is treated as a literal template; manually-added terminals
-    or run-on-build entries will be overwritten by --force. Use --diff first.
+  - .cursor/environment.json is a literal template; manually-added terminals or
+    run-on-build entries will be overwritten by --force. Use --diff first.
+  - .codex/config.toml has {{REPO_BASENAME}} substituted at scaffold time so the
+    [projects."/workspace/<repo>"] trust block matches Codex Cloud's checkout path.
+  - .gitignore: a marker-bracketed block re-includes the 5 cloud-bootstrap files
+    even when parent dirs are ignored. User content outside the markers is preserved.
+    A WARN with paste-ready fix is printed if pathological dir-only rules
+    (e.g. \`.codex/\`, \`.claude/\`) prevent re-include — change those to
+    \`.codex/*\` / \`.claude/*\` and re-run.
 `.trim();
 
 function printHelp() {
@@ -75,6 +85,7 @@ export async function initRepoCommand(args, deps = {}) {
     dryRun: !!args['--dry-run'],
     force: !!args['--force'],
     diff: !!args['--diff'],
+    noGitignore: !!args['--no-gitignore'],
   });
 
   if (result.exitCode !== 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.44-beta.10",
+  "version": "0.1.44-beta.12",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {