@ghl-ai/aw 0.1.67 → 0.1.69

package/aw-docs-validate.mjs

@@ -0,0 +1,219 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { AW_DOCS_DIR } from './constants.mjs';
+
+export const PLAN_ARTIFACTS = [
+  { kind: 'prd', source: 'prd.md', html: 'prd.html' },
+  { kind: 'design', source: 'design.md', html: 'design.html' },
+  { kind: 'spec', source: 'spec.md', html: 'spec.html' },
+  { kind: 'tasks', source: 'tasks.md', html: 'tasks.html' },
+];
+
+const GENERATED_STATUSES = new Set(['generated', 'published', 'html_generated_and_published']);
+const SKIPPED_STATUSES = new Set(['skipped']);
+
+export function findAwDocsProjectRoot(cwd = process.cwd()) {
+  let current = resolve(cwd);
+  while (true) {
+    if (existsSync(join(current, AW_DOCS_DIR))) return current;
+    const next = dirname(current);
+    if (next === current) return resolve(cwd);
+    current = next;
+  }
+}
+
+export function normalizeFeatureSlug(value) {
+  const raw = String(value || '').trim().replace(/\\/g, '/').replace(/\/+$/, '');
+  if (!raw || raw === 'true') return '';
+  const match = raw.match(/^(?:\.aw_docs\/)?features\/([^/]+)$/);
+  const slug = match ? match[1] : raw;
+  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 slug;
+}
+
+export function resolveDocsOutputMode(projectRoot, env = process.env) {
+  const configPath = join(projectRoot, AW_DOCS_DIR, 'config.json');
+  const envMode = env.AW_DOCS_OUTPUT_MODE;
+  let configMode = '';
+
+  if (existsSync(configPath)) {
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    configMode = config.docs?.outputMode || '';
+  }
+
+  return normalizeOutputMode(envMode || configMode || 'dual');
+}
+
+function normalizeOutputMode(value) {
+  const mode = String(value || 'dual').trim().toLowerCase();
+  if (mode === 'md' || mode === 'markdown-only') return 'markdown';
+  if (mode === 'html-only') return 'html';
+  if (mode === 'markdown' || mode === 'html' || mode === 'dual') return mode;
+  return 'dual';
+}
+
+export function readFeatureState(featureDir) {
+  const statePath = join(featureDir, 'state.json');
+  if (!existsSync(statePath)) return { statePath, state: null };
+  return { statePath, state: JSON.parse(readFileSync(statePath, 'utf8')) };
+}
+
+export function listExpectedPlanArtifacts(featureDir, { full = false } = {}) {
+  return PLAN_ARTIFACTS.filter(artifact => full || existsSync(join(featureDir, artifact.source)));
+}
+
+export function validateFeatureDocs(options) {
+  const projectRoot = resolve(options.projectRoot || findAwDocsProjectRoot(options.cwd));
+  const featureSlug = normalizeFeatureSlug(options.featureSlug);
+  if (!featureSlug) throw new Error('Missing feature slug. Use: aw docs validate --feature <feature-slug>');
+
+  const featureDir = join(projectRoot, AW_DOCS_DIR, 'features', featureSlug);
+  const result = {
+    ok: true,
+    projectRoot,
+    featureSlug,
+    featureDir,
+    outputMode: normalizeOutputMode(options.outputMode || resolveDocsOutputMode(projectRoot, options.env)),
+    checked: [],
+    errors: [],
+    warnings: [],
+  };
+
+  if (!existsSync(featureDir) || !statSync(featureDir).isDirectory()) {
+    addError(result, `Missing feature folder: ${AW_DOCS_DIR}/features/${featureSlug}`);
+    return result;
+  }
+
+  const { statePath, state } = readFeatureState(featureDir);
+  if (!state) {
+    addError(result, `Missing state file: ${relativeFeaturePath(projectRoot, statePath)}`);
+  }
+
+  const expected = listExpectedPlanArtifacts(featureDir, { full: options.full });
+  if (expected.length === 0) {
+    addError(result, options.full
+      ? 'Full plan validation requires prd.md, design.md, spec.md, and tasks.md.'
+      : 'No canonical planning Markdown found to validate.');
+  }
+
+  const markdownOnly = result.outputMode === 'markdown';
+  for (const artifact of expected) {
+    validateArtifact(result, artifact, { projectRoot, featureSlug, featureDir, state, markdownOnly, publishRequired: options.publishRequired });
+  }
+
+  if (state && expected.length > 0 && marksReadyForBuild(state) && result.errors.length > 0) {
+    result.warnings.push('state.json marks this feature ready for build while the HTML companion gate is failing.');
+  }
+
+  return result;
+}
+
+function validateArtifact(result, artifact, context) {
+  const sourcePath = join(context.featureDir, artifact.source);
+  const htmlPath = join(context.featureDir, artifact.html);
+  const sourceRel = featureRel(context.featureSlug, artifact.source);
+  const htmlRel = featureRel(context.featureSlug, artifact.html);
+  const entry = findCompanionEntry(context.state?.html_companion_artifacts, { sourceRel, htmlRel, kind: artifact.kind });
+
+  const record = {
+    kind: artifact.kind,
+    source: sourceRel,
+    html: htmlRel,
+    state: entry || null,
+  };
+  result.checked.push(record);
+
+  if (!existsSync(sourcePath)) {
+    addError(result, `Missing planning Markdown: ${sourceRel}`);
+    return;
+  }
+
+  if (context.markdownOnly || isExplicitMarkdownSkip(entry)) {
+    if (!context.markdownOnly && !isExplicitMarkdownSkip(entry)) {
+      addError(result, `Invalid Markdown-only skip for ${artifact.html}: missing skip_reason explicit_markdown_only.`);
+    }
+    return;
+  }
+
+  if (!existsSync(htmlPath)) {
+    addError(result, `Missing HTML companion for ${artifact.source}: ${htmlRel}`);
+  }
+
+  if (!entry) {
+    addError(result, `Missing state.json html_companion_artifacts entry for ${artifact.html}`);
+    return;
+  }
+
+  if (!GENERATED_STATUSES.has(String(entry.status || '').toLowerCase())) {
+    addError(result, `Invalid companion status for ${artifact.html}: expected generated, got ${entry.status || 'missing'}`);
+  }
+
+  if (!entry.owner || !entry.execution_mode || !entry.runner) {
+    addError(result, `Incomplete companion provenance for ${artifact.html}: owner, execution_mode, and runner are required`);
+  }
+
+  if (context.publishRequired && !hasPublishedOrBlockedLink(entry)) {
+    addError(result, `Missing publish result for ${artifact.html}: expected published links or a concrete publish blocker`);
+  }
+}
+
+function findCompanionEntry(companions, expected) {
+  if (!companions) return null;
+  const values = Array.isArray(companions)
+    ? companions
+    : Object.entries(companions).map(([key, value]) => ({ key, value }));
+
+  for (const item of values) {
+    const entry = item?.value && typeof item.value === 'object' ? item.value : item;
+    const key = item?.key || '';
+    if (!entry || typeof entry !== 'object') continue;
+    if (key === expected.htmlRel || key === basename(expected.htmlRel)) return entry;
+    if (pathMatches(entry.html_path || entry.primary || entry.publish_copy, expected.htmlRel)) return entry;
+    if (pathMatches(entry.source_path, expected.sourceRel)) return entry;
+    if (entry.artifact_kind === expected.kind || entry.kind === expected.kind) return entry;
+  }
+
+  return null;
+}
+
+function isExplicitMarkdownSkip(entry) {
+  if (!entry || typeof entry !== 'object') return false;
+  const status = String(entry.status || '').toLowerCase();
+  return SKIPPED_STATUSES.has(status) && entry.skip_reason === 'explicit_markdown_only';
+}
+
+function hasPublishedOrBlockedLink(entry) {
+  const publishStatus = String(entry.publish_status || '').toLowerCase();
+  const links = entry.remote_links || {};
+  return publishStatus === 'published'
+    || Boolean(entry.remote_url || entry.teamofone_url || entry.devtools_url || links.devtools || links.teamofone)
+    || (publishStatus === 'blocked' && Boolean(entry.publish_blocker || entry.blocked_reason));
+}
+
+function marksReadyForBuild(state) {
+  const values = [state.status, state.stage_status, state.planning_status, state.next_stage].map(value => String(value || '').toLowerCase());
+  return values.some(value => value.includes('ready_for_build') || value === 'build');
+}
+
+function pathMatches(value, expectedRel) {
+  if (!value) return false;
+  const normalized = String(value).replace(/\\/g, '/').replace(/^\.\//, '');
+  const expected = expectedRel.replace(/\\/g, '/').replace(/^\.\//, '');
+  return normalized === expected || normalized.endsWith(`/${expected}`);
+}
+
+function featureRel(featureSlug, filename) {
+  return `${AW_DOCS_DIR}/features/${featureSlug}/${filename}`;
+}
+
+function relativeFeaturePath(projectRoot, absPath) {
+  if (!isAbsolute(absPath)) return absPath;
+  return absPath.startsWith(projectRoot) ? absPath.slice(projectRoot.length + 1) : absPath;
+}
+
+function addError(result, message) {
+  result.ok = false;
+  result.errors.push(message);
+}

package/cli.mjs

@@ -19,6 +19,7 @@ const COMMANDS = {
   drop:    () => import('./commands/drop.mjs').then(m => m.dropCommand),
   status:  () => import('./commands/status.mjs').then(m => m.statusCommand),
   doctor:  () => import('./commands/doctor.mjs').then(m => m.doctorCommand),
+  docs:    () => import('./commands/docs.mjs').then(m => m.docsCommand),
   routing: () => import('./commands/startup.mjs').then(m => m.routingCommand),
   startup: () => import('./commands/startup.mjs').then(m => m.startupCommand),
   mcp:     () => import('./commands/mcp.mjs').then(m => m.mcpCommand),
@@ -159,6 +160,7 @@ function printHelp() {
     cmd('aw search <query>', 'Find agents & skills (local + registry)'),
 
     sec('Manage'),
+    cmd('aw docs validate --feature <slug>', 'Validate .aw_docs planning HTML companions before build handoff'),
     cmd('aw status', 'Show synced paths, modified files & conflicts'),
     cmd('aw doctor', 'Run a health check for routing, MCP, plugin, and AW ECC surfaces'),
     cmd('aw link', 'Link current project as a git worktree (wires IDE symlinks)'),

package/commands/docs.mjs

@@ -0,0 +1,78 @@
+import * as fmt from '../fmt.mjs';
+import { chalk } from '../fmt.mjs';
+import { validateFeatureDocs, normalizeFeatureSlug } from '../aw-docs-validate.mjs';
+
+export async function docsCommand(args) {
+  const subcommand = args._positional?.[0] || 'validate';
+  if (args['--help'] || subcommand === 'help') {
+    printDocsHelp();
+    return;
+  }
+
+  if (!['validate', 'check', 'verify'].includes(subcommand)) {
+    fmt.cancel(`Unknown aw docs command: ${subcommand}\nRun aw docs --help for usage.`);
+  }
+
+  const featureInput = args['--feature'] || args._positional?.[1];
+  let featureSlug = '';
+  try {
+    featureSlug = normalizeFeatureSlug(featureInput);
+  } catch (error) {
+    fmt.cancel(error.message);
+  }
+  if (!featureSlug) {
+    fmt.cancel('Missing feature slug. Use: aw docs validate --feature <feature-slug>');
+  }
+  const result = validateFeatureDocs({
+    cwd: process.cwd(),
+    featureSlug,
+    full: args['--full'] === true,
+    outputMode: args['--output-mode'],
+    publishRequired: args['--publish-required'] === true,
+  });
+
+  if (args['--json'] === true) {
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
+  fmt.intro('aw docs validate');
+
+  const checked = result.checked.map(item => `  ${item.kind.padEnd(6)} ${chalk.dim(item.source)} -> ${chalk.dim(item.html)}`).join('\n');
+  fmt.note([
+    `${chalk.dim('feature:')}     ${result.featureSlug}`,
+    `${chalk.dim('outputMode:')}  ${result.outputMode}`,
+    `${chalk.dim('checked:')}     ${result.checked.length}`,
+  ].join('\n'), 'Scope');
+
+  if (checked) fmt.note(checked, 'Planning Companions');
+
+  for (const warning of result.warnings) {
+    fmt.logWarn(warning);
+  }
+
+  if (!result.ok) {
+    fmt.note(result.errors.map(error => `  - ${error}`).join('\n'), chalk.red('Blocking Issues'));
+    fmt.cancel('AW docs validation failed. Run platform-core:echo-direct or record an explicit blocker before marking this feature ready.');
+  }
+
+  fmt.outro('⟁  AW docs validation passed');
+}
+
+function printDocsHelp() {
+  console.log([
+    'Usage:',
+    '  aw docs validate --feature <slug> [--full] [--publish-required] [--json]',
+    '  aw docs validate .aw_docs/features/<slug> [--full]',
+    '',
+    'Validates AW planning HTML companions before ready_for_build handoff.',
+    '',
+    'Options:',
+    '  --feature <slug>       Feature slug under .aw_docs/features/',
+    '  --full                 Require prd/design/spec/tasks Markdown and HTML companions',
+    '  --publish-required     Require Devtools/GitHub publish links or a concrete publish blocker',
+    '  --output-mode <mode>   Override docs output mode: dual, html, or markdown',
+    '  --json                 Print machine-readable result',
+  ].join('\n'));
+}

package/commands/push.mjs

@@ -37,9 +37,9 @@ import {
   AW_DOCS_SEED_BRANCH,
   AW_DOCS_PUBLISH_DIR,
   AW_DOCS_PUBLIC_BASE_URL,
-  AW_DOCS_TEAMOFONE_ORIGIN,
   AW_DOCS_TEAMOFONE_BASE_URL,
   AW_CO_AUTHOR,
+  canonicalAwDocsDevtoolsBaseUrl,
   defaultAwDocsConfig,
 } from '../constants.mjs';
 import { resolveInput } from '../paths.mjs';
@@ -252,7 +252,7 @@ function ensureAwDocsPublishConfig(projectRoot) {
     ...defaultConfig.sync.github_docs,
     ...(config.sync?.github_docs || {}),
   };
-  githubDocs.teamofone_base_url = canonicalDevtoolsBaseUrl(githubDocs.teamofone_base_url);
+  githubDocs.teamofone_base_url = canonicalAwDocsDevtoolsBaseUrl(githubDocs.teamofone_base_url);
 
   const next = {
     ...config,
@@ -306,7 +306,7 @@ function resolveAwDocsPublishConfig(projectRoot) {
     branch,
     seedBranch: process.env.AW_DOCS_SEED_BRANCH || githubDocs.seed_branch || AW_DOCS_SEED_BRANCH,
     dest,
-    teamofoneBaseUrl: canonicalDevtoolsBaseUrl(teamofoneBaseUrl),
+    teamofoneBaseUrl: canonicalAwDocsDevtoolsBaseUrl(teamofoneBaseUrl),
     publicBaseUrl,
   };
 }
@@ -554,34 +554,6 @@ function appendPathToUrl(baseUrl, path) {
   return `${basePath.replace(/\/$/, '')}/${encodedPath}${query}${hash}`;
 }
 
-function normalizeTeamOfOneBaseUrl(baseUrl) {
-  const value = String(baseUrl || '').trim();
-  if (!value) return '';
-  if (/^https?:\/\//i.test(value)) return value;
-  if (value.startsWith('/')) return `${AW_DOCS_TEAMOFONE_ORIGIN.replace(/\/$/, '')}${value}`;
-  return `https://${value.replace(/^\/+/, '')}`;
-}
-
-function canonicalDevtoolsBaseUrl(baseUrl) {
-  const canonical = AW_DOCS_TEAMOFONE_BASE_URL.replace(/\/+$/, '');
-  const normalized = normalizeTeamOfOneBaseUrl(baseUrl).replace(/\/+$/, '');
-  if (!normalized) return canonical;
-
-  try {
-    const expected = new URL(canonical);
-    const actual = new URL(normalized);
-    const expectedPath = expected.pathname.replace(/\/+$/, '');
-    const actualPath = actual.pathname.replace(/\/+$/, '');
-    if (actual.origin === expected.origin && actualPath === expectedPath) {
-      return canonical;
-    }
-  } catch {
-    return canonical;
-  }
-
-  return canonical;
-}
-
 function appendQueryParam(url, key, value) {
   const hashIndex = url.indexOf('#');
   const withoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);

package/constants.mjs

@@ -40,6 +40,34 @@ export const AW_DOCS_TEAMOFONE_ORIGIN = AW_DOCS_DEVTOOLS_ORIGIN;
 /** @deprecated Use AW_DOCS_DEVTOOLS_BASE_URL. Kept as an alias for older config keys. */
 export const AW_DOCS_TEAMOFONE_BASE_URL = AW_DOCS_DEVTOOLS_BASE_URL;
 
+function normalizeAwDocsShareBaseUrl(baseUrl) {
+  const value = String(baseUrl || '').trim();
+  if (!value) return '';
+  if (/^https?:\/\//i.test(value)) return value;
+  if (value.startsWith('/')) return `${AW_DOCS_DEVTOOLS_ORIGIN.replace(/\/$/, '')}${value}`;
+  return `https://${value.replace(/^\/+/, '')}`;
+}
+
+export function canonicalAwDocsDevtoolsBaseUrl(baseUrl) {
+  const canonical = AW_DOCS_DEVTOOLS_BASE_URL.replace(/\/+$/, '');
+  const normalized = normalizeAwDocsShareBaseUrl(baseUrl).replace(/\/+$/, '');
+  if (!normalized) return canonical;
+
+  try {
+    const expected = new URL(canonical);
+    const actual = new URL(normalized);
+    const expectedPath = expected.pathname.replace(/\/+$/, '');
+    const actualPath = actual.pathname.replace(/\/+$/, '');
+    if (actual.origin === expected.origin && actualPath === expectedPath) {
+      return canonical;
+    }
+  } catch {
+    return canonical;
+  }
+
+  return canonical;
+}
+
 export function defaultAwDocsGithubDocsConfig() {
   return {
     enabled: true,

package/ecc.mjs

@@ -12,7 +12,7 @@ import { applyStoredStartupPreferences } from "./startup.mjs";
 
 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.65";
+export const AW_ECC_TAG = "v1.4.66";
 const REQUIRED_ECC_FILES = [
   "package.json",
   "scripts/install-apply.js",

package/integrate.mjs

@@ -15,6 +15,7 @@ import {
 import { isDefaultRoutingEnabled } from './startup.mjs';
 import {
   AW_DOCS_DIR,
+  canonicalAwDocsDevtoolsBaseUrl,
   defaultAwDocsConfig,
 } from './constants.mjs';
 
@@ -665,6 +666,7 @@ No active runs. Use \`/aw:<team>-<command>\` to start a workflow.
           github_docs: {
             ...defaultConfig.sync.github_docs,
             ...(existing.sync?.github_docs || {}),
+            teamofone_base_url: canonicalAwDocsDevtoolsBaseUrl(existing.sync?.github_docs?.teamofone_base_url),
           },
         },
         paths: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.67",
+  "version": "0.1.69",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {
@@ -29,6 +29,7 @@
     "slack-sim/",
     "file-tree.mjs",
     "apply.mjs",
+    "aw-docs-validate.mjs",
     "hook-cleanup.mjs",
     "hook-manifest.mjs",
     "update.mjs",