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

package/cli.mjs

@@ -50,6 +50,9 @@ function parseArgs(argv) {
     if (arg === '--dry-run') {
       args['--dry-run'] = true;
       i++;
+    } else if (arg === '--aw-docs-only' || arg === '--docs-only') {
+      args[arg] = true;
+      i++;
     } else if (arg === '-v' || arg === '--verbose') {
       args['-v'] = true;
       i++;
@@ -99,6 +102,7 @@ function printHelp() {
     sec('Upload'),
     cmd('aw push', 'Push all modified files (creates one PR)'),
     cmd('aw push --aw-docs-only', 'Publish generated .aw_docs companions and print share links'),
+    cmd('aw push --aw-docs-only --feature <slug>', 'Publish one .aw_docs feature folder and print share links'),
     cmd('aw push <path>', 'Push file, folder, or namespace to registry'),
     cmd('aw push-rules [path]', 'Push platform rules to platform-docs'),
     cmd('aw push --dry-run [path]', 'Preview what would be pushed'),

package/commands/push.mjs

@@ -144,13 +144,71 @@ function collectFiles(root, base = root) {
   return files;
 }
 
-function collectProjectAwDocs(cwd, home) {
+function normalizeRelPath(value) {
+  return String(value || '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/\/+$/, '');
+}
+
+function featureScopeFromInput(input) {
+  const value = normalizeRelPath(input);
+  if (!value) return null;
+
+  const match = value.match(/^(?:\.aw_docs\/)?features\/([^/]+)$/);
+  if (!match) {
+    throw new Error('Docs-only publish path must be .aw_docs/features/<feature-slug> or use --feature <feature-slug>.');
+  }
+  return awDocsFeatureScope(match[1]);
+}
+
+function awDocsFeatureScope(featureSlug) {
+  const slug = String(featureSlug || '').trim();
+  if (!slug || slug === 'true') {
+    throw new Error('Missing feature slug. Use: aw push --aw-docs-only --feature <feature-slug>');
+  }
+  if (!/^[A-Za-z0-9._-]+$/.test(slug)) {
+    throw new Error(`Invalid feature slug "${slug}". Feature slugs may contain letters, numbers, dot, underscore, and dash only.`);
+  }
+  return {
+    type: 'feature',
+    slug,
+    relPrefix: `features/${slug}`,
+  };
+}
+
+function resolveAwDocsScope(input, featureFlag) {
+  const inputScope = featureScopeFromInput(input);
+  const flagScope = featureFlag ? awDocsFeatureScope(featureFlag) : null;
+  if (inputScope && flagScope && inputScope.relPrefix !== flagScope.relPrefix) {
+    throw new Error(`Docs-only publish received conflicting scopes: ${inputScope.relPrefix} and ${flagScope.relPrefix}.`);
+  }
+  return flagScope || inputScope;
+}
+
+function collectProjectAwDocs(cwd, home, scope = null) {
   const projectRoot = getProjectRoot(cwd, home);
   const source = join(projectRoot, AW_DOCS_DIR);
 
   if (!existsSync(source)) return { projectRoot, files: [] };
 
   const files = [];
+  if (scope) {
+    const sourceRoot = join(source, scope.relPrefix);
+    if (!existsSync(sourceRoot) || !statSync(sourceRoot).isDirectory()) {
+      throw new Error(`No publishable AW docs found under ${AW_DOCS_DIR}/${scope.relPrefix}.`);
+    }
+    for (const relFromRoot of collectFiles(sourceRoot)) {
+      const relPath = `${scope.relPrefix}/${relFromRoot}`.replace(/\\/g, '/');
+      files.push({
+        relPath,
+        absPath: join(source, relPath),
+      });
+    }
+    return { projectRoot, files };
+  }
+
   for (const root of PROJECT_AW_DOCS_AUTO_ROOTS) {
     const sourceRoot = join(source, root);
     if (!existsSync(sourceRoot)) continue;
@@ -480,7 +538,7 @@ function titleForAwDoc(relPath) {
   return `${label} ${ext}`;
 }
 
-function updateAwDocsManifest(docsRepoDir, { repoSlug, sourceRepo, githubUsername, docs, publishConfig }) {
+function updateAwDocsManifest(docsRepoDir, { repoSlug, sourceRepo, githubUsername, docs, publishConfig, scope = null }) {
   const manifestPath = join(docsRepoDir, 'manifest.json');
   const manifest = existsSync(manifestPath)
     ? JSON.parse(readFileSync(manifestPath, 'utf8'))
@@ -494,25 +552,32 @@ function updateAwDocsManifest(docsRepoDir, { repoSlug, sourceRepo, githubUsernam
   repoEntry.slug = repoSlug;
   repoEntry.sourceRepo = sourceRepo;
   repoEntry.users ||= {};
+  const existingUser = repoEntry.users[githubUsername] || {};
+  const nextDocs = docs.map(doc => ({
+    relPath: doc.relPath,
+    publishedPath: doc.publishedPath,
+    remoteUrl: awDocsRemoteUrl(doc.publishedPath, publishConfig),
+    repositoryUrl: awDocsRepositoryUrl(doc.publishedPath, publishConfig),
+    sha: createHash('sha256').update(readFileSync(join(docsRepoDir, doc.publishedPath))).digest('hex'),
+    syncedAt: now,
+    title: titleForAwDoc(doc.relPath),
+  }));
+  const preservedDocs = scope?.relPrefix
+    ? (existingUser.docs || []).filter(doc => !String(doc.relPath || '').startsWith(`${scope.relPrefix}/`))
+    : [];
+
   repoEntry.users[githubUsername] = {
+    ...existingUser,
     githubUsername,
-    docs: docs.map(doc => ({
-      relPath: doc.relPath,
-      publishedPath: doc.publishedPath,
-      remoteUrl: awDocsRemoteUrl(doc.publishedPath, publishConfig),
-      repositoryUrl: awDocsRepositoryUrl(doc.publishedPath, publishConfig),
-      sha: createHash('sha256').update(readFileSync(join(docsRepoDir, doc.publishedPath))).digest('hex'),
-      syncedAt: now,
-      title: titleForAwDoc(doc.relPath),
-    })),
+    docs: scope?.relPrefix ? [...preservedDocs, ...nextDocs] : nextDocs,
   };
   manifest.awDocs.repos[repoSlug] = repoEntry;
 
   writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
 }
 
-async function publishProjectAwDocs(cwd, home, dryRun) {
-  const { projectRoot, files } = collectProjectAwDocs(cwd, home);
+async function publishProjectAwDocs(cwd, home, dryRun, scope = null) {
+  const { projectRoot, files } = collectProjectAwDocs(cwd, home, scope);
   if (files.length === 0) return { hasDocs: false, publishedPaths: [] };
 
   const publishConfig = resolveAwDocsPublishConfig(projectRoot);
@@ -551,7 +616,10 @@ async function publishProjectAwDocs(cwd, home, dryRun) {
   s.start(`Publishing ${files.length} AW doc${files.length > 1 ? 's' : ''} to ${publishConfig.repo}...`);
   try {
     const docsRepoDir = await ensureAwDocsRepoClone(home, publishConfig);
-    rmSync(join(docsRepoDir, publishConfig.dest, repoSlug, githubUsername), {
+    const deleteTarget = scope?.relPrefix
+      ? join(docsRepoDir, publishConfig.dest, repoSlug, githubUsername, scope.relPrefix)
+      : join(docsRepoDir, publishConfig.dest, repoSlug, githubUsername);
+    rmSync(deleteTarget, {
       recursive: true,
       force: true,
     });
@@ -560,7 +628,7 @@ async function publishProjectAwDocs(cwd, home, dryRun) {
       mkdirSync(dirname(dest), { recursive: true });
       copyFileSync(doc.absPath, dest);
     }
-    updateAwDocsManifest(docsRepoDir, { repoSlug, sourceRepo, githubUsername, docs, publishConfig });
+    updateAwDocsManifest(docsRepoDir, { repoSlug, sourceRepo, githubUsername, docs, publishConfig, scope });
 
     const { stdout: status } = await execFile('git', ['status', '--porcelain'], {
       cwd: docsRepoDir,
@@ -574,7 +642,9 @@ async function publishProjectAwDocs(cwd, home, dryRun) {
     }
 
     await commitAndPushAwDocsRepo(docsRepoDir, {
-      message: `docs(aw): sync ${repoSlug}/${githubUsername} AW docs`,
+      message: scope?.relPrefix
+        ? `docs(aw): sync ${repoSlug}/${githubUsername} ${scope.relPrefix}`
+        : `docs(aw): sync ${repoSlug}/${githubUsername} AW docs`,
       branch: publishConfig.branch,
     });
     writeAwDocsLinkSummary(projectRoot, links, publishConfig);
@@ -1074,14 +1144,13 @@ export async function pushCommand(args) {
   }
 
   if (docsOnly) {
-    if (input) {
-      fmt.cancel('Docs-only publish does not accept a path. Run: aw push --aw-docs-only');
-      return;
-    }
     try {
-      const result = await publishProjectAwDocs(cwd, HOME, dryRun);
+      const scope = resolveAwDocsScope(input, args['--feature']);
+      const result = await publishProjectAwDocs(cwd, HOME, dryRun, scope);
       if (!result.hasDocs) {
-        fmt.cancel('No publishable AW docs found under .aw_docs/features or .aw_docs/html.');
+        fmt.cancel(scope
+          ? `No publishable AW docs found under ${AW_DOCS_DIR}/${scope.relPrefix}.`
+          : 'No publishable AW docs found under .aw_docs/features or .aw_docs/html.');
         return;
       }
       if (dryRun) fmt.outro(chalk.dim('Remove --dry-run to publish AW docs'));

package/package.json

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