@ghl-ai/aw 0.1.81 → 0.1.83

package/commands/push.mjs

@@ -431,6 +431,10 @@ async function removeTrackedAwSymlink(cloneDir) {
     return false;
   }
 
+  // `.aw` is always kept inside the sparse-checkout cone (see AW_DOCS_CACHE_PATH
+  // in ensureAwDocsRepoClone) so this remove works even on blobless/sparse
+  // clones. Without that, git rejects the rm with "outside sparse-checkout
+  // definition" against repos that track a real .aw/ tree (e.g. ghl-aw-docs).
   await execFile('git', ['rm', '-f', '.aw'], {
     cwd: cloneDir,
     encoding: 'utf8',
@@ -572,32 +576,97 @@ 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');
-
-  if (!existsSync(join(cloneDir, '.git'))) {
-    await execFile('git', ['clone', publishConfig.repoUrl, cloneDir], {
+// 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;
+// `.aw` is always kept in the sparse-checkout cone. The docs repo may track a
+// real `.aw/` tree (e.g. ghl-aw-docs tracks `.aw/.aw_rules/**`), and the
+// cache-management code (removeTrackedAwSymlink, selfHeal*) runs write git ops
+// on `.aw`. Excluding it from the cone makes those ops fail with "outside
+// sparse-checkout definition" and breaks every publish against such a repo.
+const AW_DOCS_CACHE_PATH = '.aw';
+
+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, AW_DOCS_CACHE_PATH], {
+        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, AW_DOCS_CACHE_PATH], {
+      cwd: cloneDir,
+      encoding: 'utf8',
+    }).catch(() => { /* best effort — checkout below still works */ });
+  }
+
   const hasPublishBranch = await remoteBranchExists(cloneDir, publishConfig.branch);
   const checkoutStart = hasPublishBranch
     ? `origin/${publishConfig.branch}`
@@ -608,9 +677,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)
@@ -622,6 +695,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,
     });
   }
 
@@ -629,6 +704,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);
@@ -729,6 +806,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,
   });
 }
 
@@ -823,7 +902,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

package/package.json

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