@erclx/aitk 0.8.0

package/src/commands/standards.ts

@@ -0,0 +1,89 @@
+import { join } from 'node:path'
+import type { Command } from 'commander'
+import { registerPassThroughVerbs } from '@/commands/pass-through'
+import { PROJECT_ROOT } from '@/exec'
+import { createStandardsAdapter, standardsSourceDir } from '@/standards/adapter'
+import {
+  refreshIndex,
+  STANDARDS_REL,
+  standardsInstallDir,
+} from '@/standards/index-refresh'
+import { applyInstall, planInstall } from '@/standards/install'
+import { recordStamp, runDomainSync } from '@/sync/engine'
+import { resolveTarget } from '@/target'
+import { intro, logAdd, logInfo, logStep, logWarn, outro, select } from '@/ui'
+
+const GREEN = '\x1b[0;32m'
+const GREY = '\x1b[0;90m'
+const NC = '\x1b[0m'
+
+export function register(program: Command): void {
+  const standards = program
+    .command('standards')
+    .description('Standards commands (install, sync, list)')
+    .helpOption('-h, --help', 'Show this help message')
+
+  standards
+    .command('sync')
+    .description('Update standards already installed under .claude/standards/')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .action(async (target: string) => {
+      process.exitCode = await runDomainSync(
+        createStandardsAdapter(PROJECT_ROOT),
+        target,
+        { protectedRoot: PROJECT_ROOT },
+      )
+    })
+
+  standards
+    .command('install')
+    .description('Copy all standards into a project (overwrites)')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .action(async (target: string) => {
+      process.exitCode = await runInstall(target)
+    })
+
+  registerPassThroughVerbs(standards, 'standards', ['list'])
+}
+
+async function runInstall(target: string): Promise<number> {
+  intro('aitk standards')
+
+  const resolved = resolveTarget(target, PROJECT_ROOT)
+  if (typeof resolved === 'number') return resolved
+
+  const sourceDir = standardsSourceDir(PROJECT_ROOT)
+  const destDir = standardsInstallDir(resolved)
+
+  logStep('Scanning standards')
+  const files = planInstall(sourceDir)
+  for (const file of files) logInfo(join(STANDARDS_REL, file.name))
+
+  const shouldInstall = await select({
+    message: `Install ${files.length} standards to ${destDir}?`,
+    options: [
+      { value: true, label: 'Yes' },
+      { value: false, label: 'No' },
+    ],
+    nonInteractiveDefault: true,
+  })
+
+  if (!shouldInstall) {
+    logWarn('Cancelled')
+    outro()
+    return 0
+  }
+
+  logStep('Installing standards')
+  for (const label of await applyInstall(files, destDir)) logAdd(label)
+  await refreshIndex(sourceDir, resolved)
+  await recordStamp(createStandardsAdapter(PROJECT_ROOT), resolved, new Date())
+
+  outro()
+  process.stderr.write(
+    `\n${GREEN}✓ Standards installed${NC} ${GREY}(${files.length} files)${NC}\n`,
+  )
+  return 0
+}

package/src/commands/sync.ts

@@ -0,0 +1,211 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Command } from 'commander'
+import { cliPath, cliRun } from '@/cli-run'
+import { PROJECT_ROOT } from '@/exec'
+import { buildCheckReport, type CheckReport, hasDrift } from '@/sync/check'
+import { createGitRunner, createPullRequestOpener, hasGh } from '@/sync/git'
+import { STAMP_DOMAINS } from '@/sync/stamp'
+import {
+  detectDomains,
+  installedDomains,
+  isTreeClean,
+  shouldSync,
+  SYNC_DOMAINS,
+  type SyncDomain,
+} from '@/sync/target'
+import { runGitWorkflow } from '@/sync/workflow'
+import { resolveTarget } from '@/target'
+import {
+  intro,
+  isNonInteractive,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+} from '@/ui'
+
+const GREY = '\x1b[0;90m'
+const YELLOW = '\x1b[0;33m'
+const NC = '\x1b[0m'
+
+const SYNC_ARGS: Record<SyncDomain, readonly string[]> = {
+  standards: ['standards', 'sync'],
+  snippets: ['snippets', 'sync'],
+  governance: ['gov', 'sync'],
+  claude: ['claude', 'sync'],
+}
+
+interface SyncOptions {
+  readonly check?: boolean
+  readonly json?: boolean
+  readonly exitCode?: boolean
+}
+
+export function register(program: Command): void {
+  program
+    .command('sync')
+    .description('Sync all installed domains in a project')
+    .argument('[target]', 'Target directory', '.')
+    .option('--check', 'Report drift without writing anything')
+    .option('--json', 'Emit the drift report as JSON on stdout')
+    .option('--exit-code', 'Exit 1 when drift is found, for CI')
+    .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Examples:',
+        '  aitk sync',
+        '  aitk sync ../my-app',
+        '  aitk sync --check',
+        '  aitk sync --check --json',
+        '  aitk sync --check --exit-code',
+        '',
+      ].join('\n'),
+    )
+    .action(async (target: string, options: SyncOptions) => {
+      process.exitCode =
+        options.check === true
+          ? await runCheck(target, options)
+          : await runSync(target)
+    })
+}
+
+/**
+ * Reads the same plan a sync would apply and writes nothing. Drift between
+ * syncs is normal, so the default exit stays 0 and CI opts into failing.
+ */
+async function runCheck(target: string, options: SyncOptions): Promise<number> {
+  const resolved = resolveTarget(target, PROJECT_ROOT)
+  if (typeof resolved === 'number') return resolved
+
+  const report = await buildCheckReport(PROJECT_ROOT, resolved)
+
+  if (options.json === true) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  } else {
+    renderCheck(report)
+  }
+
+  return options.exitCode === true && hasDrift(report) ? 1 : 0
+}
+
+function renderCheck(report: CheckReport): void {
+  intro('aitk sync --check')
+
+  for (const domain of report.domains) {
+    logStep(domain.domain)
+
+    if (domain.commit === undefined) {
+      logWarn('Not stamped. Drift below is reported unattributed.')
+    } else {
+      logInfo(`Synced from ${domain.commit} on ${domain.syncedAt}`)
+    }
+
+    for (const entry of domain.entries) {
+      if (entry.state === 'matching' || entry.state === 'orphaned') continue
+      logWarn(`${entry.rel} (${entry.state})`)
+    }
+
+    const { stale, customized, drifted, stranded, orphaned } = domain.counts
+    if (stale + customized + drifted + stranded === 0) {
+      logInfo(orphaned === 0 ? 'up to date' : `up to date (${orphaned} local)`)
+    }
+
+    for (const commit of domain.upstream) {
+      logInfo(`${commit.sha} ${commit.subject}`)
+    }
+  }
+
+  if (report.newSkills.length > 0) {
+    logStep('New skills, no sync needed')
+    for (const name of report.newSkills) logInfo(name)
+  }
+
+  outro()
+  const uncovered = STAMP_DOMAINS.filter(
+    (domain) => !report.covers.includes(domain),
+  )
+  const unstamped =
+    uncovered.length === 0 ? '' : `Unstamped: ${uncovered.join(', ')}. `
+  process.stderr.write(
+    `${GREY}${unstamped}Tooling is never stamped, run \`aitk tooling\` to reconcile configs.${NC}\n`,
+  )
+}
+
+async function runSync(target: string): Promise<number> {
+  intro('aitk sync')
+
+  const resolved = resolveTarget(target, PROJECT_ROOT)
+  if (typeof resolved === 'number') return resolved
+
+  const git = createGitRunner(resolved)
+
+  logStep('Checking working tree')
+  if (!isTreeClean(await git.status([]))) {
+    logError(
+      'Working tree has uncommitted changes. Commit or stash before syncing.',
+    )
+    outro()
+    return 1
+  }
+  logInfo('Working tree clean')
+
+  logStep('Detecting domains')
+  const states = detectDomains(resolved)
+  for (const state of states) {
+    if (state.installed) logInfo(state.domain)
+    else logWarn(`${state.domain} (not installed, skipping)`)
+  }
+
+  if (installedDomains(states).length === 0) {
+    outro()
+    process.stderr.write(
+      `\n${YELLOW}! No domains installed in target. Run domain install commands first.${NC}\n`,
+    )
+    return 0
+  }
+
+  outro()
+  process.stderr.write('\n')
+
+  await runDomainSyncs(resolved)
+
+  const code = await runGitWorkflow(resolved, {
+    git,
+    pullRequests: (await hasGh())
+      ? createPullRequestOpener(resolved)
+      : undefined,
+    now: new Date(),
+    nonInteractive: isNonInteractive(),
+  })
+
+  if (existsSync(join(resolved, '.claude'))) {
+    process.stderr.write(
+      `${GREY}Tip: run \`/claude-seed-sync\` to audit seed and standards drift per section, preserving local customizations.${NC}\n`,
+    )
+  }
+
+  return code
+}
+
+/**
+ * Each domain sync runs as its own process. They open their own frames and
+ * prompt for their own changes, so stdin stays inherited. Claude is the one
+ * exception: it runs headless because the combined pull request preview is the
+ * single confirmation gate for the whole sync, and `aitk claude sync` writes
+ * only `.gitignore`.
+ */
+async function runDomainSyncs(target: string): Promise<void> {
+  const path = cliPath(PROJECT_ROOT)
+
+  for (const domain of SYNC_DOMAINS) {
+    if (!shouldSync(target, domain)) continue
+
+    await cliRun(path, [...SYNC_ARGS[domain], target], {
+      nonInteractive: domain === 'claude',
+    })()
+  }
+}

package/src/commands/tasks.ts

@@ -0,0 +1,185 @@
+import { relative } from 'node:path'
+import { $ } from 'bun'
+import type { Command } from 'commander'
+import { type ArchiveOutcome, archiveTask } from '@/tasks/archive'
+import {
+  intro,
+  logAdd,
+  logError,
+  logInfo,
+  logRemove,
+  logStep,
+  outro,
+  pipeOutput,
+} from '@/ui'
+
+interface ArchiveCommandOptions {
+  readonly json?: boolean
+  readonly pullRequest?: string
+  readonly root?: string
+}
+
+/**
+ * The board is shared scratch at the main worktree root, and `git worktree
+ * list` puts that root first. A pull inside a linked worktree fires the same
+ * hook, so trusting the working directory would write a second board nothing
+ * else reads.
+ */
+async function mainWorktreeRoot(): Promise<string> {
+  const result = await $`git worktree list --porcelain`.quiet().nothrow()
+  if (result.exitCode !== 0) return process.cwd()
+
+  const line = result.stdout
+    .toString()
+    .split('\n')
+    .find((entry) => entry.startsWith('worktree '))
+
+  return line ? line.slice('worktree '.length).trim() : process.cwd()
+}
+
+export function register(program: Command): void {
+  const tasks = program
+    .command('tasks')
+    .description('Manage the task board in .claude/tasks/')
+    .helpOption('-h, --help', 'Show this help message')
+
+  tasks
+    .command('archive')
+    .description('Move a shipped task out of the board and clear its ordering')
+    .argument('[task]', 'Task filename stem, as in v28.1-trigger-escalation')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--pull-request <number>',
+      'Select the task naming this pull request',
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the task was archived',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  aitk tasks archive v28.1-trigger-escalation',
+        '  aitk tasks archive --pull-request 673 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (task: string | undefined, opts: ArchiveCommandOptions) => {
+      process.exitCode = await runArchive(task, opts)
+    })
+}
+
+async function runArchive(
+  task: string | undefined,
+  opts: ArchiveCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (task && opts.pullRequest) {
+    return report(
+      {
+        ok: false,
+        reason: 'ambiguous',
+        message: 'Name a task or a pull request, not both.',
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  if (!task && !opts.pullRequest) {
+    return report(
+      {
+        ok: false,
+        reason: 'no-match',
+        message:
+          'No task named. Pass a filename stem or --pull-request <number>.',
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+
+  if (opts.pullRequest && !/^\d+$/.test(opts.pullRequest)) {
+    return report(
+      {
+        ok: false,
+        reason: 'no-match',
+        message: `Not a pull request number: ${opts.pullRequest}`,
+        detail: [],
+      },
+      emitJson,
+      root,
+    )
+  }
+
+  const outcome = await archiveTask(
+    root,
+    task
+      ? { kind: 'stem', stem: task }
+      : { kind: 'pull-request', number: Number(opts.pullRequest) },
+  )
+
+  return report(outcome, emitJson, root)
+}
+
+function report(
+  outcome: ArchiveOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify(recordFor(outcome, root))}\n`)
+    return outcome.ok ? 0 : 1
+  }
+
+  intro('aitk tasks archive')
+
+  if (!outcome.ok) {
+    logStep('Refused')
+    logError(outcome.message)
+    if (outcome.detail.length > 0) pipeOutput(outcome.detail.join('\n'))
+    outro()
+    return 1
+  }
+
+  logStep('Archived')
+  logRemove(relative(root, outcome.from))
+  logAdd(relative(root, outcome.to))
+  if (outcome.priorityRowRemoved) logInfo('cleared the ordering row')
+  if (outcome.indexRegenerated) logInfo('regenerated index.md')
+  outro()
+
+  return 0
+}
+
+function recordFor(
+  outcome: ArchiveOutcome,
+  root: string,
+): Record<string, unknown> {
+  if (!outcome.ok) {
+    return {
+      ok: false,
+      reason: outcome.reason,
+      message: outcome.message,
+      detail: outcome.detail,
+    }
+  }
+
+  return {
+    ok: true,
+    task: outcome.stem,
+    from: relative(root, outcome.from),
+    to: relative(root, outcome.to),
+    priorityRowRemoved: outcome.priorityRowRemoved,
+    indexRegenerated: outcome.indexRegenerated,
+  }
+}