@ghl-ai/aw 0.1.80 → 0.1.82

package/cli.mjs

@@ -63,6 +63,9 @@ function parseArgs(argv) {
     } else if (arg === '-y') {
       args['-y'] = true;
       i++;
+    } else if (arg === '--yes' || arg === '--non-interactive' || arg === '--headless') {
+      args[arg] = true;
+      i++;
     } else if (arg === '--version') {
       args['--version'] = true;
       i++;
@@ -154,6 +157,7 @@ function printHelp() {
     sec('Upload'),
     cmd('aw push', 'Push all modified files (creates one PR)'),
     cmd('aw push --aw-docs-only --feature <slug>', 'Publish one .aw_docs feature folder and print share links'),
+    cmd('aw push --aw-docs-only --yes', 'Publish in CI/headless mode (no TTY spinner; auto when CI=1)'),
     cmd('aw push --aw-docs-only --all', 'Publish ALL .aw_docs feature folders (explicit opt-in; otherwise scope with --feature)'),
     cmd('aw push <path>', 'Push file, folder, or namespace to registry'),
     cmd('aw push-rules [path]', 'Push platform rules to platform-docs'),

package/commands/push.mjs

@@ -23,7 +23,7 @@ import { createHash } from 'node:crypto';
 const exec = promisify(execCb);
 const execFile = promisify(execFileCb);
 import * as fmt from '../fmt.mjs';
-import { chalk } from '../fmt.mjs';
+import { chalk, configureInteractionMode } from '../fmt.mjs';
 import {
   REGISTRY_REPO,
   REGISTRY_URL,
@@ -158,18 +158,64 @@ function normalizeRelPath(value) {
 // and full nested folders. Use for shared, repo-keyed doc trees such as PR
 // reviews (pr-reviews/<owner>/<repo>/pr-<n>/<run>) so they do not land under the
 // reviewer's workspace namespace as one mangled flat slug.
-const AW_DOCS_ROOT_NAMESPACES = ['pr-reviews'];
+const AW_DOCS_ROOT_NAMESPACES = ['pr-reviews', 'security-audits'];
+
+// Compound root prefixes (multi-segment). Longest match wins in matchRootPrefix().
+const AW_DOCS_ROOT_PREFIX_RULES = [
+  { prefix: 'security/audit', minSegments: 4 },
+  { prefix: 'pr-reviews', minSegments: 4 },
+  { prefix: 'security-audits', minSegments: 3 },
+];
+
+// Minimum nested depth per root namespace. A root scope's delete-then-copy
+// target is the resolved subtree, so a shallow path (e.g. `pr-reviews` or
+// `security-audits/<repo>`) must be rejected — otherwise it could resolve to a
+// broad shared subtree and wipe unrelated runs on the remote.
+//   pr-reviews/<repo>/pr-<number>/<run>  → 4 segments
+//   security-audits/<repo>/<date>        → 3 segments
+//   security/audit/<repo>/<run-id>       → 4 segments
+const AW_DOCS_ROOT_MIN_SEGMENTS = {
+  'pr-reviews': 4,
+  'security-audits': 3,
+};
+
+function normalizeAwDocsRootInput(stripped) {
+  if (stripped.startsWith('security/audit/')) {
+    return stripped.replace(/^security\/audit\//, 'security-audits/');
+  }
+  return stripped;
+}
+
+function ensureHeadlessGitEnv() {
+  if (!fmt.isHeadless()) return;
+  if (process.env.GIT_TERMINAL_PROMPT === undefined) process.env.GIT_TERMINAL_PROMPT = '0';
+  if (process.env.GCM_INTERACTIVE === undefined) process.env.GCM_INTERACTIVE = 'never';
+}
+
+function matchRootPrefix(stripped) {
+  const value = normalizeRelPath(stripped);
+  const rules = [...AW_DOCS_ROOT_PREFIX_RULES].sort((a, b) => b.prefix.length - a.prefix.length);
+  for (const rule of rules) {
+    if (value === rule.prefix || value.startsWith(`${rule.prefix}/`)) {
+      return rule;
+    }
+  }
+  const first = value.split('/')[0];
+  if (AW_DOCS_ROOT_NAMESPACES.includes(first)) {
+    return { prefix: first, minSegments: AW_DOCS_ROOT_MIN_SEGMENTS[first] };
+  }
+  return null;
+}
 
 function awDocsRootScope(relPath) {
   const value = normalizeRelPath(relPath);
   const segments = value.split('/');
-  // A root scope's delete-then-copy target is the resolved subtree. Require the
-  // full pr-reviews/<repo>/pr-<number>/<run> depth so a shallow path (e.g.
-  // `pr-reviews` or `pr-reviews/<repo>`) can never resolve to a broad shared
-  // subtree and wipe unrelated review runs on the remote.
-  if (segments[0] !== 'pr-reviews' || segments.length < 4) {
+  const rule = matchRootPrefix(value);
+  if (!rule || segments.length < rule.minSegments) {
     throw new Error(
-      `Root-scope docs publish must target pr-reviews/<repo>/pr-<number>/<run>, got "${relPath}".`
+      'Root-scope docs publish must target pr-reviews/<repo>/pr-<number>/<run>, ' +
+      'security-audits/<repo>/<date>, or security/audit/<repo>/<run-id>, ' +
+      `got "${relPath}".`
     );
   }
   for (const seg of segments) {
@@ -184,14 +230,14 @@ function featureScopeFromInput(input) {
   const value = normalizeRelPath(input);
   if (!value) return null;
 
-  const stripped = value.replace(/^\.aw_docs\//, '');
-  if (AW_DOCS_ROOT_NAMESPACES.includes(stripped.split('/')[0])) {
+  const stripped = normalizeAwDocsRootInput(value.replace(/^\.aw_docs\//, ''));
+  if (matchRootPrefix(stripped)) {
     return awDocsRootScope(stripped);
   }
 
   const match = value.match(/^(?:\.aw_docs\/)?features\/([^/]+)$/);
   if (!match) {
-    throw new Error('Docs-only publish path must be .aw_docs/features/<feature-slug>, .aw_docs/pr-reviews/<...>, or use --feature <feature-slug>.');
+    throw new Error('Docs-only publish path must be .aw_docs/features/<feature-slug>, .aw_docs/pr-reviews/<...>, .aw_docs/security-audits/<...> (or legacy .aw_docs/security/audit/<...>), or use --feature <feature-slug>.');
   }
   return awDocsFeatureScope(match[1]);
 }
@@ -526,32 +572,91 @@ async function getProjectSourceRepo(projectRoot) {
   return `local/${basename(projectRoot)}`;
 }
 
-async function ensureAwDocsRepoClone(home, publishConfig) {
-  const cloneDir = process.env.AW_DOCS_WORKTREE || join(home, '.aw-ghl-aw-docs');
+// Network git ops against the docs repo always disable interactive credential
+// prompts (so a missing/incorrect credential fails fast instead of hanging
+// forever) and are time-bounded (so a stalled connection aborts instead of
+// blocking the whole publish). Override the caps with AW_DOCS_GIT_TIMEOUT_MS.
+const AW_DOCS_GIT_ENV = { ...process.env, GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'never' };
+const AW_DOCS_CLONE_TIMEOUT_MS = Number(process.env.AW_DOCS_GIT_TIMEOUT_MS) || 180000;
+const AW_DOCS_NET_TIMEOUT_MS = Number(process.env.AW_DOCS_GIT_TIMEOUT_MS) || 120000;
 
-  if (!existsSync(join(cloneDir, '.git'))) {
-    await execFile('git', ['clone', publishConfig.repoUrl, cloneDir], {
+async function awDocsSparseEnabled(cloneDir) {
+  try {
+    const { stdout } = await execFile('git', ['config', '--get', 'core.sparseCheckout'], {
+      cwd: cloneDir,
       encoding: 'utf8',
     });
+    return stdout.trim() === 'true';
+  } catch {
+    return false;
   }
+}
 
-  let status = await getGitStatus(cloneDir);
-  if (status.trim() && await selfHealManagedAwCacheDirtiness(cloneDir, status)) {
-    status = await getGitStatus(cloneDir);
+async function ensureAwDocsRepoClone(home, publishConfig, sparseIncludePaths = []) {
+  const cloneDir = process.env.AW_DOCS_WORKTREE || join(home, '.aw-ghl-aw-docs');
+  const wantSparse = sparseIncludePaths.length > 0;
+  const freshClone = !existsSync(join(cloneDir, '.git'));
+
+  if (freshClone) {
+    // A full clone of ghl-aw-docs pulls the entire org's published docs
+    // (hundreds of MB / ~170k objects) and is the dominant cause of
+    // first-publish timeouts. Clone blobless (no file contents up front) and,
+    // when we know which subtree this publish touches, defer checkout and
+    // sparse-checkout only that path — turning hundreds of MB into a few MB.
+    // Degrades gracefully: if the remote does not support partial clone git
+    // ignores the filter, and if sparse-checkout is unavailable the branch
+    // checkout below still materialises the full tree.
+    const cloneArgs = ['clone', '--filter=blob:none'];
+    if (wantSparse) cloneArgs.push('--no-checkout');
+    cloneArgs.push(publishConfig.repoUrl, cloneDir);
+    await execFile('git', cloneArgs, {
+      encoding: 'utf8',
+      env: AW_DOCS_GIT_ENV,
+      timeout: AW_DOCS_CLONE_TIMEOUT_MS,
+    });
+    if (wantSparse) {
+      await execFile('git', ['sparse-checkout', 'set', '--cone', ...sparseIncludePaths], {
+        cwd: cloneDir,
+        encoding: 'utf8',
+      }).catch(() => { /* sparse unsupported → full checkout below */ });
+    }
   }
-  if (status.trim()) {
-    throw new Error([
-      `AW docs repo worktree is dirty: ${cloneDir}`,
-      status.trim(),
-      'Clean the cached docs repo or set AW_DOCS_WORKTREE to a clean clone before publishing.',
-    ].join('\n'));
+
+  // Only validate cleanliness for a REUSED clone. A fresh blobless
+  // --no-checkout clone intentionally has no working tree yet (it is
+  // materialised by the branch checkout below), which would otherwise
+  // register as "dirty".
+  if (!freshClone) {
+    let status = await getGitStatus(cloneDir);
+    if (status.trim() && await selfHealManagedAwCacheDirtiness(cloneDir, status)) {
+      status = await getGitStatus(cloneDir);
+    }
+    if (status.trim()) {
+      throw new Error([
+        `AW docs repo worktree is dirty: ${cloneDir}`,
+        status.trim(),
+        'Clean the cached docs repo or set AW_DOCS_WORKTREE to a clean clone before publishing.',
+      ].join('\n'));
+    }
   }
 
   await execFile('git', ['fetch', 'origin'], {
     cwd: cloneDir,
     encoding: 'utf8',
+    env: AW_DOCS_GIT_ENV,
+    timeout: AW_DOCS_NET_TIMEOUT_MS,
   });
 
+  // Keep the current publish's subtree inside the sparse cone. Only applies to
+  // clones that already use sparse-checkout (i.e. the blobless clones we
+  // created) — legacy full clones are left untouched so there is no regression.
+  if (wantSparse && await awDocsSparseEnabled(cloneDir)) {
+    await execFile('git', ['sparse-checkout', 'add', ...sparseIncludePaths], {
+      cwd: cloneDir,
+      encoding: 'utf8',
+    }).catch(() => { /* best effort — checkout below still works */ });
+  }
+
   const hasPublishBranch = await remoteBranchExists(cloneDir, publishConfig.branch);
   const checkoutStart = hasPublishBranch
     ? `origin/${publishConfig.branch}`
@@ -562,9 +667,13 @@ async function ensureAwDocsRepoClone(home, publishConfig) {
   }
 
   try {
+    // With a blobless clone, checkout lazily fetches the missing blobs for the
+    // sparse cone — a network op, so bound it like the other remote calls.
     await execFile('git', ['checkout', '-B', publishConfig.branch, checkoutStart], {
       cwd: cloneDir,
       encoding: 'utf8',
+      env: AW_DOCS_GIT_ENV,
+      timeout: AW_DOCS_NET_TIMEOUT_MS,
     });
   } catch (e) {
     const healedPath = isCheckoutOverwrittenByAwPathError(e)
@@ -576,6 +685,8 @@ async function ensureAwDocsRepoClone(home, publishConfig) {
     await execFile('git', ['checkout', '-B', publishConfig.branch, checkoutStart], {
       cwd: cloneDir,
       encoding: 'utf8',
+      env: AW_DOCS_GIT_ENV,
+      timeout: AW_DOCS_NET_TIMEOUT_MS,
     });
   }
 
@@ -583,6 +694,8 @@ async function ensureAwDocsRepoClone(home, publishConfig) {
     await execFile('git', ['pull', '--ff-only', 'origin', publishConfig.branch], {
       cwd: cloneDir,
       encoding: 'utf8',
+      env: AW_DOCS_GIT_ENV,
+      timeout: AW_DOCS_NET_TIMEOUT_MS,
     });
   }
   await removeTrackedAwSymlink(cloneDir);
@@ -683,6 +796,8 @@ async function commitAndPushAwDocsRepo(docsRepoDir, { message, branch }) {
   await execFile('git', ['push', '-u', 'origin', `HEAD:${branch}`], {
     cwd: docsRepoDir,
     encoding: 'utf8',
+    env: AW_DOCS_GIT_ENV,
+    timeout: AW_DOCS_NET_TIMEOUT_MS,
   });
 }
 
@@ -733,6 +848,7 @@ function updateAwDocsManifest(docsRepoDir, { repoSlug, sourceRepo, githubUsernam
 }
 
 async function publishProjectAwDocs(cwd, home, dryRun, scope = null) {
+  ensureHeadlessGitEnv();
   const { projectRoot, files } = collectProjectAwDocs(cwd, home, scope);
   if (files.length === 0) return { hasDocs: false, publishedPaths: [] };
 
@@ -776,7 +892,12 @@ async function publishProjectAwDocs(cwd, home, dryRun, scope = null) {
   const s = fmt.spinner();
   s.start(`Publishing ${files.length} AW doc${files.length > 1 ? 's' : ''} to ${publishConfig.repo}...`);
   try {
-    const docsRepoDir = await ensureAwDocsRepoClone(home, publishConfig);
+    // Scope the (blobless) docs clone to only the subtree this publish writes,
+    // so a fresh clone fetches a few MB instead of the whole org's docs.
+    const sparseIncludePaths = isRootScope
+      ? [`${publishConfig.dest}/${scope.relPrefix}`]
+      : [`${publishConfig.dest}/${repoSlug}/${githubUsername}`];
+    const docsRepoDir = await ensureAwDocsRepoClone(home, publishConfig, sparseIncludePaths);
     const deleteTarget = isRootScope
       ? join(docsRepoDir, publishConfig.dest, scope.relPrefix)
       : scope?.relPrefix
@@ -1326,6 +1447,8 @@ async function doPush(files, awHome, dryRun, worktreeFlow = false, preStaged = f
 // ── Main command ─────────────────────────────────────────────────────
 
 export async function pushCommand(args) {
+  configureInteractionMode(args);
+
   const input = args._positional?.[0];
   const dryRun = args['--dry-run'] === true;
   const docsOnly = args['--aw-docs-only'] === true || args['--docs-only'] === true;
@@ -1684,6 +1807,8 @@ export const __test__ = {
   featureScopeFromInput,
   awDocsFeatureScope,
   awDocsRootScope,
+  matchRootPrefix,
+  normalizeAwDocsRootInput,
   resolveAwDocsScope,
   assertDocsOnlyScopeOrAll,
   getGitHubUser,

package/fmt.mjs

@@ -13,6 +13,38 @@ let _silent = false;
 export function setSilent(v) { _silent = !!v; }
 export function isSilent() { return _silent; }
 
+// ─── Headless mode ───
+// CI / non-TTY / --yes: skip clack TTY UI (intro, spinner, p.cancel) but keep log output.
+let _headless = false;
+export function setHeadless(v) { _headless = !!v; }
+export function isHeadless() { return _headless; }
+
+function envTruthy(name) {
+  const value = String(process.env[name] || '').trim().toLowerCase();
+  return value === '1' || value === 'true' || value === 'yes';
+}
+
+/** Configure silent/headless interaction before command output. */
+export function configureInteractionMode(args = {}) {
+  if (args['--silent'] === true) {
+    setSilent(true);
+    setHeadless(true);
+    return { silent: true, headless: true };
+  }
+
+  const forceHeadless = args['--yes'] === true
+    || args['-y'] === true
+    || args['--non-interactive'] === true
+    || args['--headless'] === true;
+  const headless = forceHeadless
+    || envTruthy('CI')
+    || envTruthy('AW_NON_INTERACTIVE')
+    || !process.stdout.isTTY;
+
+  setHeadless(headless);
+  return { silent: false, headless };
+}
+
 // ─── Banner ───
 
 // Big ASCII art icons — same height as ANSI Shadow font (6 lines)
@@ -73,14 +105,27 @@ export function banner(text, opts = {}) {
 
 // ─── Clack wrappers ───
 
-export const intro    = (msg) => { if (!_silent) p.intro(chalk.bgHex('#FF6B35').black(` ⟁  ${msg} `)); };
-export const outro    = (msg) => { if (!_silent) p.outro(chalk.green(msg)); };
+export const intro    = (msg) => { if (!_silent && !_headless) p.intro(chalk.bgHex('#FF6B35').black(` ⟁  ${msg} `)); };
+export const outro    = (msg) => {
+  if (_silent) return;
+  if (_headless) { console.log(msg); return; }
+  p.outro(chalk.green(msg));
+};
 export const select   = p.select;
 export const isCancel = p.isCancel;
 
-// Returns a real spinner when not silent, or a no-op stub when silent.
-const _noopSpinner = { start() {}, stop() {}, message() {} };
-export const spinner = () => _silent ? _noopSpinner : p.spinner();
+// Returns a real spinner when interactive, or a stub in silent/headless mode.
+const _silentSpinner = { start() {}, stop() {}, message() {} };
+const _headlessSpinner = {
+  start() {},
+  stop(msg) { if (msg) console.log(msg); },
+  message() {},
+};
+export const spinner = () => {
+  if (_silent) return _silentSpinner;
+  if (_headless) return _headlessSpinner;
+  return p.spinner();
+};
 
 export class CancelError extends Error {
   constructor(message, { exitCode = 1 } = {}) {
@@ -91,13 +136,15 @@ export class CancelError extends Error {
 }
 
 export function cancel(msg) {
-  p.cancel(msg);
+  if (_headless) console.error(msg);
+  else p.cancel(msg);
   throw new CancelError(msg);
 }
 
 /** Hard exit — for use in process exception handlers where throwing is unsafe */
 export function cancelAndExit(msg) {
-  p.cancel(msg);
+  if (_headless) console.error(msg);
+  else p.cancel(msg);
   process.exit(1);
 }
 

package/package.json

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