opencastle 0.1.0

package/src/cli/run.ts

@@ -0,0 +1,137 @@
+import { resolve } from 'node:path'
+import { parseTaskSpec } from './run/schema.js'
+import { createExecutor, buildPhases } from './run/executor.js'
+import { getAdapter } from './run/adapters/index.js'
+import { createReporter, printExecutionPlan } from './run/reporter.js'
+import type { CliContext, RunOptions } from './types.js'
+
+const HELP = `
+  opencastle run [options]
+
+  Process a task queue from a spec file, delegating to AI agents autonomously.
+
+  Options:
+    --file, -f <path>        Task spec file (default: opencastle.tasks.yml)
+    --dry-run                Show execution plan without running
+    --concurrency, -c <n>    Override max parallel tasks
+    --adapter, -a <name>     Override agent runtime adapter
+    --report-dir <path>      Where to write run reports (default: .opencastle/runs)
+    --verbose                Show full agent output
+    --help, -h               Show this help
+`
+
+/**
+ * Parse CLI arguments for the run command.
+ */
+function parseArgs(args: string[]): RunOptions {
+  const opts: RunOptions = {
+    file: 'opencastle.tasks.yml',
+    dryRun: false,
+    concurrency: null,
+    adapter: null,
+    reportDir: null,
+    verbose: false,
+    help: false,
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    switch (arg) {
+      case '--help':
+      case '-h':
+        opts.help = true
+        break
+      case '--file':
+      case '-f':
+        opts.file = args[++i]
+        break
+      case '--dry-run':
+        opts.dryRun = true
+        break
+      case '--concurrency':
+      case '-c': {
+        const val = parseInt(args[++i], 10)
+        if (!Number.isFinite(val) || val < 1) {
+          console.error(`  ✗ --concurrency must be an integer >= 1`)
+          process.exit(1)
+        }
+        opts.concurrency = val
+        break
+      }
+      case '--adapter':
+      case '-a':
+        opts.adapter = args[++i]
+        break
+      case '--report-dir':
+        opts.reportDir = args[++i]
+        break
+      case '--verbose':
+        opts.verbose = true
+        break
+      default:
+        console.error(`  ✗ Unknown option: ${arg}`)
+        console.log(HELP)
+        process.exit(1)
+    }
+  }
+
+  return opts
+}
+
+/**
+ * CLI entry point for the `run` command.
+ */
+export default async function run({ args }: CliContext): Promise<void> {
+  const opts = parseArgs(args)
+
+  if (opts.help) {
+    console.log(HELP)
+    return
+  }
+
+  // ── Read and validate spec ────────────────────────────────────
+  const specPath = resolve(process.cwd(), opts.file)
+  const spec = await parseTaskSpec(specPath)
+
+  // Apply CLI overrides
+  if (opts.concurrency !== null) spec.concurrency = opts.concurrency
+  if (opts.adapter !== null) spec.adapter = opts.adapter
+  if (opts.verbose) spec._verbose = true
+
+  // ── Dry run ──────────────────────────────────────────────────
+  const phases = buildPhases(spec.tasks)
+
+  if (opts.dryRun) {
+    printExecutionPlan(spec, phases)
+    return
+  }
+
+  // ── Check adapter ────────────────────────────────────────────
+  const adapter = await getAdapter(spec.adapter)
+  const available = await adapter.isAvailable()
+  if (!available) {
+    console.error(
+      `  ✗ Adapter "${spec.adapter}" is not available.\n` +
+        `    Make sure the "${spec.adapter === 'claude-code' ? 'claude' : spec.adapter}" CLI is installed and on your PATH.`
+    )
+    process.exit(1)
+  }
+
+  // ── Execute ──────────────────────────────────────────────────
+  console.log(`\n  🏰 OpenCastle Run: ${spec.name}`)
+  console.log(`  Adapter: ${adapter.name} | Concurrency: ${spec.concurrency} | Tasks: ${spec.tasks.length}`)
+
+  const reporter = createReporter(spec, {
+    reportDir: opts.reportDir
+      ? resolve(process.cwd(), opts.reportDir)
+      : undefined,
+    verbose: opts.verbose,
+  })
+
+  const executor = createExecutor(spec, adapter, reporter)
+  const report = await executor.run()
+
+  // ── Exit code ────────────────────────────────────────────────
+  const hasFailures = report.summary.failed > 0 || report.summary['timed-out'] > 0
+  process.exit(hasFailures ? 1 : 0)
+}

package/src/cli/stack-config.ts

@@ -0,0 +1,180 @@
+import type { CmsChoice, DbChoice, PmChoice, NotifChoice, StackConfig, CopyDirOptions } from './types.js';
+
+// ── Skill / Technology labels ─────────────────────────────────
+
+/** Display name for each CMS choice */
+const CMS_LABELS: Record<Exclude<CmsChoice, 'none'>, { tech: string; skill: string }> = {
+  sanity: { tech: 'Sanity', skill: 'sanity-cms' },
+  contentful: { tech: 'Contentful', skill: 'contentful-cms' },
+  strapi: { tech: 'Strapi', skill: 'strapi-cms' },
+};
+
+/** Display name for each DB choice */
+const DB_LABELS: Record<Exclude<DbChoice, 'none'>, { tech: string; skill: string }> = {
+  supabase: { tech: 'Supabase', skill: 'supabase-database' },
+  convex: { tech: 'Convex', skill: 'convex-database' },
+};
+
+/** Display name for each PM choice */
+const PM_LABELS: Record<Exclude<PmChoice, 'none'>, { tech: string; skill: string }> = {
+  linear: { tech: 'Linear', skill: 'task-management' },
+  jira: { tech: 'Jira', skill: 'jira-management' },
+};
+
+/** Display name for each notifications choice */
+const NOTIF_LABELS: Record<Exclude<NotifChoice, 'none'>, { tech: string; skill: string }> = {
+  slack: { tech: 'Slack', skill: 'slack-notifications' },
+  teams: { tech: 'Teams', skill: 'teams-notifications' },
+};
+
+// ── Exclusion / inclusion maps ────────────────────────────────
+
+/** Skills to EXCLUDE based on CMS choice */
+const CMS_SKILL_MAP: Record<CmsChoice, string[]> = {
+  sanity: ['contentful-cms', 'strapi-cms'],
+  contentful: ['sanity-cms', 'strapi-cms'],
+  strapi: ['sanity-cms', 'contentful-cms'],
+  none: ['sanity-cms', 'contentful-cms', 'strapi-cms'],
+};
+
+/** Skills to EXCLUDE based on DB choice */
+const DB_SKILL_MAP: Record<DbChoice, string[]> = {
+  supabase: ['convex-database'],
+  convex: ['supabase-database'],
+  none: ['supabase-database', 'convex-database'],
+};
+
+/** Skills to EXCLUDE based on PM choice */
+const PM_SKILL_MAP: Record<PmChoice, string[]> = {
+  linear: ['jira-management'],
+  jira: ['task-management'],
+  none: ['task-management', 'jira-management'],
+};
+
+/** Agents to EXCLUDE based on CMS choice */
+const CMS_AGENT_EXCLUSIONS: Record<CmsChoice, string[]> = {
+  sanity: [],
+  contentful: [],
+  strapi: [],
+  none: ['content-engineer.agent.md'],
+};
+
+/** Agents to EXCLUDE based on DB choice */
+const DB_AGENT_EXCLUSIONS: Record<DbChoice, string[]> = {
+  supabase: [],
+  convex: [],
+  none: ['database-engineer.agent.md'],
+};
+
+/** MCP server keys to INCLUDE based on CMS choice */
+const CMS_MCP_MAP: Record<CmsChoice, string[]> = {
+  sanity: ['Sanity'],
+  contentful: ['Contentful'],
+  strapi: ['Strapi'],
+  none: [],
+};
+
+/** MCP server keys to INCLUDE based on DB choice */
+const DB_MCP_MAP: Record<DbChoice, string[]> = {
+  supabase: ['Supabase'],
+  convex: ['Convex'],
+  none: [],
+};
+
+/** MCP server keys to INCLUDE based on PM choice */
+const PM_MCP_MAP: Record<PmChoice, string[]> = {
+  linear: ['Linear'],
+  jira: ['Jira'],
+  none: [],
+};
+
+/** Skills to EXCLUDE based on notifications choice */
+const NOTIF_SKILL_MAP: Record<NotifChoice, string[]> = {
+  slack: ['teams-notifications'],
+  teams: ['slack-notifications'],
+  none: ['slack-notifications', 'teams-notifications'],
+};
+
+/** MCP server keys to INCLUDE based on notifications choice */
+const NOTIF_MCP_MAP: Record<NotifChoice, string[]> = {
+  slack: ['Slack'],
+  teams: ['Teams'],
+  none: [],
+};
+
+/** Always-included MCP servers */
+const CORE_MCP_SERVERS = ['chrome-devtools', 'Vercel'];
+
+export function getExcludedSkills(stack: StackConfig): Set<string> {
+  return new Set([
+    ...CMS_SKILL_MAP[stack.cms],
+    ...DB_SKILL_MAP[stack.db],
+    ...PM_SKILL_MAP[stack.pm],
+    ...NOTIF_SKILL_MAP[stack.notifications],
+  ]);
+}
+
+export function getExcludedAgents(stack: StackConfig): Set<string> {
+  return new Set([
+    ...CMS_AGENT_EXCLUSIONS[stack.cms],
+    ...DB_AGENT_EXCLUSIONS[stack.db],
+  ]);
+}
+
+export function getIncludedMcpServers(stack: StackConfig): Set<string> {
+  return new Set([
+    ...CORE_MCP_SERVERS,
+    ...CMS_MCP_MAP[stack.cms],
+    ...DB_MCP_MAP[stack.db],
+    ...PM_MCP_MAP[stack.pm],
+    ...NOTIF_MCP_MAP[stack.notifications],
+  ]);
+}
+
+// ── Customization file transforms ─────────────────────────────
+
+/**
+ * Return a transform callback that pre-populates customization files
+ * based on the user's stack selection.
+ *
+ * Used by all adapters when copying the `customizations/` directory.
+ */
+export function getCustomizationsTransform(
+  stack: StackConfig
+): NonNullable<CopyDirOptions['transform']> {
+  return (content: string, srcPath: string) => {
+    // Pre-fill skill matrix with CMS and DB bindings
+    if (srcPath.endsWith('skill-matrix.md')) {
+      return transformSkillMatrix(content, stack);
+    }
+    return content;
+  };
+}
+
+/**
+ * Fill in the `database` and `cms` rows in the skill matrix
+ * based on the user's stack selection.
+ */
+function transformSkillMatrix(content: string, stack: StackConfig): string {
+  let result = content;
+
+  // Fill the database row
+  if (stack.db !== 'none') {
+    const { tech, skill } = DB_LABELS[stack.db];
+    result = result.replace(
+      /(\| `database`\s*\|)\s*\|(\s*\|)/,
+      `$1 ${tech} | \`${skill}\` $2`
+    );
+  }
+
+  // Fill the CMS row
+  if (stack.cms !== 'none') {
+    const { tech, skill } = CMS_LABELS[stack.cms];
+    result = result.replace(
+      /(\| `cms`\s*\|)\s*\|(\s*\|)/,
+      `$1 ${tech} | \`${skill}\` $2`
+    );
+  }
+
+  return result;
+}

package/src/cli/types.ts

@@ -0,0 +1,207 @@
+import type { ChildProcess } from 'node:child_process';
+
+// ── Stack selection types ──────────────────────────────────────
+
+export type CmsChoice = 'sanity' | 'contentful' | 'strapi' | 'none';
+export type DbChoice = 'supabase' | 'convex' | 'none';
+export type PmChoice = 'linear' | 'jira' | 'none';
+export type NotifChoice = 'slack' | 'teams' | 'none';
+
+export interface StackConfig {
+  cms: CmsChoice;
+  db: DbChoice;
+  pm: PmChoice;
+  notifications: NotifChoice;
+}
+
+/** Context passed from bin/cli.mjs to every command handler. */
+export interface CliContext {
+  pkgRoot: string;
+  args: string[];
+}
+
+/** Results from a copy/install/update operation. */
+export interface CopyResults {
+  copied: string[];
+  skipped: string[];
+  created: string[];
+}
+
+/** Options for the copyDir utility. */
+export interface CopyDirOptions {
+  overwrite?: boolean;
+  filter?: (_name: string, _srcPath: string) => boolean;
+  transform?: (
+    _content: string,
+    _srcPath: string
+  ) => Promise<string | null> | string | null;
+}
+
+/** OpenCastle project manifest (.opencastle.json). */
+export interface Manifest {
+  version: string;
+  ide: string;
+  installedAt: string;
+  updatedAt: string;
+  managedPaths?: ManagedPaths;
+  stack?: StackConfig;
+}
+
+/** Framework vs customizable file paths. */
+export interface ManagedPaths {
+  framework: string[];
+  customizable: string[];
+}
+
+/** IDE adapter interface (init/update commands). */
+export interface IdeAdapter {
+  install(_pkgRoot: string, _projectRoot: string, _stack?: StackConfig): Promise<CopyResults>;
+  update(_pkgRoot: string, _projectRoot: string, _stack?: StackConfig): Promise<CopyResults>;
+  getManagedPaths(): ManagedPaths;
+}
+
+/** Select prompt option. */
+export interface SelectOption {
+  label: string;
+  hint?: string;
+  value: string;
+}
+
+/** Scaffold result from MCP config. */
+export interface ScaffoldResult {
+  path: string;
+  action: 'created' | 'skipped';
+}
+
+// ── Run command types ──────────────────────────────────────────
+
+/** Validated task spec from YAML. */
+export interface TaskSpec {
+  name: string;
+  concurrency: number;
+  on_failure: 'continue' | 'stop';
+  adapter: string;
+  tasks: Task[];
+  _verbose?: boolean;
+}
+
+/** A single task in the spec. */
+export interface Task {
+  id: string;
+  prompt: string;
+  agent: string;
+  timeout: string;
+  depends_on: string[];
+  files: string[];
+  description: string;
+  _process?: ChildProcess;
+}
+
+/** Task execution status. */
+export type TaskStatus =
+  | 'pending'
+  | 'running'
+  | 'done'
+  | 'failed'
+  | 'skipped'
+  | 'timed-out';
+
+/** Result of a single task execution. */
+export interface TaskResult {
+  id: string;
+  status: TaskStatus;
+  duration: number;
+  output: string;
+  exitCode: number;
+}
+
+/** Final run report. */
+export interface RunReport {
+  name: string;
+  startedAt: string;
+  completedAt: string;
+  duration: string;
+  summary: RunSummary;
+  tasks: TaskResult[];
+}
+
+/** Summary counts of task statuses. */
+export interface RunSummary {
+  total: number;
+  done: number;
+  failed: number;
+  skipped: number;
+  'timed-out': number;
+}
+
+/** Agent runtime adapter for the run command. */
+export interface AgentAdapter {
+  name: string;
+  isAvailable(): Promise<boolean>;
+  execute(_task: Task, _options?: ExecuteOptions): Promise<ExecuteResult>;
+  kill?(_task: Task): void;
+}
+
+/** Options for agent execution. */
+export interface ExecuteOptions {
+  verbose?: boolean;
+}
+
+/** Result from an agent adapter execution. */
+export interface ExecuteResult {
+  success: boolean;
+  output: string;
+  exitCode: number;
+  _timedOut?: boolean;
+  taskId?: string;
+}
+
+/** Reporter interface for the run command. */
+export interface Reporter {
+  onTaskStart(_task: Task): void;
+  onTaskDone(_task: Task, _result: TaskResult): void;
+  onTaskSkipped(_task: Task, _reason: string): void;
+  onPhaseStart(_phase: number, _tasks: Task[]): void;
+  onComplete(_report: RunReport): Promise<void>;
+}
+
+/** Reporter options. */
+export interface ReporterOptions {
+  reportDir?: string;
+  verbose?: boolean;
+}
+
+/** Parsed CLI args for the run command. */
+export interface RunOptions {
+  file: string;
+  dryRun: boolean;
+  concurrency: number | null;
+  adapter: string | null;
+  reportDir: string | null;
+  verbose: boolean;
+  help: boolean;
+}
+
+/** Parse result from YAML block parser. */
+export interface ParseResult {
+  value: unknown;
+  nextIndex: number;
+}
+
+/** Validation result. */
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/** Timeout promise with cancel ability. */
+export interface TimeoutHandle {
+  promise: Promise<ExecuteResult>;
+  clear: () => void;
+}
+
+/** Executor returned by createExecutor. */
+export interface Executor {
+  run(): Promise<RunReport>;
+  getPhases(): Task[][];
+}

package/src/cli/update.ts

@@ -0,0 +1,75 @@
+import { resolve } from 'node:path'
+import { readFile } from 'node:fs/promises'
+import { readManifest, writeManifest } from './manifest.js'
+import { confirm, closePrompts } from './prompt.js'
+import type { CliContext, IdeAdapter } from './types.js'
+
+const ADAPTERS: Record<string, () => Promise<IdeAdapter>> = {
+  vscode: () => import('./adapters/vscode.js') as Promise<IdeAdapter>,
+  cursor: () => import('./adapters/cursor.js') as Promise<IdeAdapter>,
+  'claude-code': () =>
+    import('./adapters/claude-code.js') as Promise<IdeAdapter>,
+}
+
+const VALID_IDES = Object.keys(ADAPTERS)
+
+export default async function update({
+  pkgRoot,
+  args,
+}: CliContext): Promise<void> {
+  const projectRoot = process.cwd()
+
+  const manifest = await readManifest(projectRoot)
+  if (!manifest) {
+    console.error(
+      '  ✗ No OpenCastle installation found. Run "npx opencastle init" first.'
+    )
+    process.exit(1)
+  }
+
+  if (!manifest.ide || !VALID_IDES.includes(manifest.ide)) {
+    console.error(
+      `  ✗ Invalid IDE "${manifest.ide}" in .opencastle.json. Valid options: ${VALID_IDES.join(', ')}`
+    )
+    process.exit(1)
+  }
+
+  const pkg = JSON.parse(
+    await readFile(resolve(pkgRoot, 'package.json'), 'utf8')
+  ) as { version: string }
+
+  if (manifest.version === pkg.version && !args.includes('--force')) {
+    console.log(`  Already up to date (v${pkg.version}).`)
+    return
+  }
+
+  console.log(
+    `\n  🏰 OpenCastle update: v${manifest.version} → v${pkg.version}\n`
+  )
+  console.log(`  IDE: ${manifest.ide}`)
+  console.log('  Framework files will be overwritten.')
+  console.log('  Customization files will be preserved.\n')
+
+  const proceed = await confirm('Proceed with update?')
+  if (!proceed) {
+    console.log('  Aborted.')
+    return
+  }
+
+  const adapter = await ADAPTERS[manifest.ide]()
+  const results = await adapter.update(pkgRoot, projectRoot)
+
+  // Update manifest
+  manifest.version = pkg.version
+  manifest.updatedAt = new Date().toISOString()
+  manifest.managedPaths = adapter.getManagedPaths()
+  await writeManifest(projectRoot, manifest)
+
+  console.log(`\n  ✓ Updated ${results.copied.length} framework files`)
+  if (results.created.length > 0) {
+    console.log(`  + Created ${results.created.length} new files`)
+  }
+  console.log()
+
+  closePrompts()
+}

package/src/dashboard/astro.config.mjs

@@ -0,0 +1,6 @@
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  site: 'https://www.opencastle.dev',
+  base: process.env.DASHBOARD_BASE || '/',
+});