@antomanc/aginit 0.1.0

package/src/adapters/skills.ts

@@ -0,0 +1,117 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileExists, readJsonFile } from '../utils/fs.js';
+import { runExecutable } from '../utils/shell.js';
+import { logger } from '../utils/logger.js';
+import { validateUpstreamArgument } from '../config/validation.js';
+import { SkillSourceConfig } from '../config/schema.js';
+
+export interface SkillsLockFile {
+  version: number;
+  skills: Record<
+    string,
+    {
+      source: string;
+      sourceType: string;
+      skillPath: string;
+      computedHash: string;
+    }
+  >;
+}
+
+export interface SkillInstallOptions {
+  agents?: string[];
+  dryRun?: boolean;
+  silent?: boolean;
+}
+
+export async function installSkillSource(
+  targetDir: string,
+  source: SkillSourceConfig,
+  options: SkillInstallOptions = {}
+): Promise<{ ok: boolean; message?: string }> {
+  const { agents = ['antigravity', 'codex'], dryRun = false, silent = false } = options;
+
+  validateUpstreamArgument(source.package, 'skill package');
+  for (const skill of source.skills) validateUpstreamArgument(skill, 'skill name');
+  for (const agent of agents) validateUpstreamArgument(agent, 'agent');
+  const args = [
+    '-y',
+    'skills',
+    'add',
+    source.package,
+    '--skill',
+    ...(source.skills.length ? source.skills : ['*']),
+    '--agent',
+    ...agents,
+    '-y'
+  ];
+
+  if (!silent) {
+    logger.dim(`Installing skills from ${source.package}: ${source.skills.join(', ')}...`);
+  }
+
+  const res = await runExecutable('npx', args, { cwd: targetDir, dryRun, silent: true });
+  if (!res.ok) {
+    logger.warn(`Failed installing skills from ${source.package}: ${res.stderr || res.stdout}`);
+    return { ok: false, message: res.stderr || res.stdout };
+  }
+
+  return { ok: true };
+}
+
+export async function installAllSkills(
+  targetDir: string,
+  sources: SkillSourceConfig[],
+  options: SkillInstallOptions = {}
+): Promise<{ installed: string[]; failed: string[] }> {
+  const installed: string[] = [];
+  const failed: string[] = [];
+
+  for (const source of sources) {
+    const res = await installSkillSource(targetDir, source, options);
+    if (res.ok) {
+      installed.push(...(source.skills.length ? source.skills : [`${source.package}:*`]));
+    } else {
+      failed.push(...(source.skills.length ? source.skills : [`${source.package}:*`]));
+    }
+  }
+
+  return { installed, failed };
+}
+
+export function getInstalledSkills(targetDir: string): string[] {
+  const lockPath = path.join(targetDir, 'skills-lock.json');
+  if (fileExists(lockPath)) {
+    const lock = readJsonFile<SkillsLockFile>(lockPath);
+    if (lock && lock.skills) {
+      return Object.keys(lock.skills);
+    }
+  }
+
+  // Check .agents/skills directory directly
+  const skillsDir = path.join(targetDir, '.agents', 'skills');
+  if (fileExists(skillsDir)) {
+    try {
+      return fs.readdirSync(skillsDir).filter((f) => !f.startsWith('.'));
+    } catch {
+      return [];
+    }
+  }
+
+  return [];
+}
+
+export async function updateSkills(
+  targetDir: string,
+  options: { dryRun?: boolean; silent?: boolean } = {}
+): Promise<boolean> {
+  const { dryRun = false, silent = false } = options;
+  if (!silent) logger.dim('Updating installed skills...');
+  const res = await runExecutable('npx', ['-y', 'skills', 'update', '-p', '-y'], {
+    cwd: targetDir,
+    dryRun,
+    silent: true
+  });
+  return res.ok;
+}

package/src/cli/doctor.ts

@@ -0,0 +1,244 @@
+import path from 'node:path';
+import pc from 'picocolors';
+import { runExecutable, commandExists } from '../utils/shell.js';
+import { fileExists, readTextFile } from '../utils/fs.js';
+import {
+  AGINIT_CONFIG_FILENAME,
+  LEGACY_CONFIG_FILENAME,
+  AginitConfig,
+  PackageManager
+} from '../config/schema.js';
+import { detectPackageManager } from '../adapters/package-manager.js';
+import { getInstalledSkills } from '../adapters/skills.js';
+import { readProjectConfig } from '../config/validation.js';
+import { logger } from '../utils/logger.js';
+
+interface CheckItem {
+  name: string;
+  category: 'Environment' | 'AI Tooling' | 'Project Config';
+  ok: boolean;
+  version?: string;
+  detail: string;
+  suggestion?: string;
+}
+
+export async function runDoctor(targetDir: string = process.cwd()): Promise<void> {
+  logger.banner('Aginit — System & Project Doctor', `Target: ${targetDir}`);
+
+  // Resolve project config early to detect configured package manager
+  let configPath = path.join(targetDir, AGINIT_CONFIG_FILENAME);
+  if (!fileExists(configPath)) {
+    const legacyPath = path.join(targetDir, LEGACY_CONFIG_FILENAME);
+    if (fileExists(legacyPath)) {
+      configPath = legacyPath;
+    }
+  }
+
+  const configExists = fileExists(configPath);
+  let projectConfig: AginitConfig | null = null;
+  let configError = '';
+  try {
+    projectConfig = readProjectConfig(targetDir);
+  } catch (error) {
+    configError = error instanceof Error ? error.message : String(error);
+  }
+  const activePm: PackageManager =
+    projectConfig?.packageManager || detectPackageManager(targetDir) || 'pnpm';
+
+  const checks: CheckItem[] = [];
+
+  // 1. Node.js check
+  const nodeRes = await runExecutable('node', ['-v'], { silent: true });
+  let nodeOk = nodeRes.ok;
+  let nodeDetail = 'Node.js is not found in PATH';
+  let nodeSuggestion: string | undefined =
+    'Install Node.js (>= 22.12.0 LTS recommended) via nvm, fnm, or brew';
+  if (nodeRes.ok) {
+    const rawVer = nodeRes.stdout.replace(/^v/, '');
+    const [major = 0, minor = 0] = rawVer.split('.').map(Number);
+    const meetsEngine = major > 22 || (major === 22 && minor >= 12);
+    if (meetsEngine) {
+      nodeDetail = `Installed (${nodeRes.stdout})`;
+      nodeSuggestion = undefined;
+    } else {
+      nodeOk = false;
+      nodeDetail = `Installed (${nodeRes.stdout}) — requires Node.js >= 22.12.0`;
+      nodeSuggestion = 'Upgrade Node.js to >= 22.12.0 (LTS) via nvm, fnm, or brew';
+    }
+  }
+  checks.push({
+    name: 'Node.js runtime',
+    category: 'Environment',
+    ok: nodeOk,
+    version: nodeRes.stdout,
+    detail: nodeDetail,
+    suggestion: nodeSuggestion
+  });
+
+  // 2. Active Package Manager check (pnpm, npm, yarn, or bun)
+  const pmRes = await runExecutable(activePm, ['-v'], { silent: true });
+  checks.push({
+    name: `${activePm} package manager`,
+    category: 'Environment',
+    ok: pmRes.ok,
+    version: pmRes.stdout,
+    detail: pmRes.ok ? `Installed (${pmRes.stdout})` : `${activePm} is not found in PATH`,
+    suggestion: pmRes.ok
+      ? undefined
+      : `Install ${activePm} (${activePm === 'pnpm' ? 'npm install -g pnpm' : activePm === 'bun' ? 'curl -fsSL https://bun.sh/install | bash' : 'install ' + activePm})`
+  });
+
+  // 3. Git check
+  const gitExists = await commandExists('git');
+  let isGitRepo = fileExists(path.join(targetDir, '.git'));
+  let inWorkTree = false;
+  if (gitExists && !isGitRepo) {
+    const revParse = await runExecutable('git', ['rev-parse', '--is-inside-work-tree'], {
+      cwd: targetDir,
+      silent: true
+    });
+    if (revParse.ok && revParse.stdout === 'true') {
+      isGitRepo = true;
+      inWorkTree = true;
+    }
+  }
+  checks.push({
+    name: 'Git VCS',
+    category: 'Environment',
+    ok: gitExists && isGitRepo,
+    detail: gitExists
+      ? isGitRepo
+        ? inWorkTree
+          ? 'Git installed and target directory is within an active git repository'
+          : 'Git installed and repository initialized'
+        : 'Git installed, but target directory is not a git repo'
+      : 'Git is not installed',
+    suggestion: !gitExists
+      ? 'Install git via brew or Xcode Command Line Tools'
+      : !isGitRepo
+        ? 'Run `git init` or `aginit init` to initialize repository'
+        : undefined
+  });
+
+  // 4. Graft CLI check
+  const graftExists = await commandExists('graft');
+  let graftVersion = '';
+  if (graftExists) {
+    const gv = await runExecutable('graft', ['--version'], { silent: true });
+    graftVersion = gv.stdout;
+  }
+  checks.push({
+    name: 'Graft codebase graph CLI',
+    category: 'AI Tooling',
+    ok: graftExists,
+    version: graftVersion,
+    detail: graftExists ? `Installed globally (${graftVersion})` : 'Graft CLI not found in PATH',
+    suggestion: graftExists ? undefined : 'Install Graft: `npm install -g @nanonets/graft`'
+  });
+
+  // 5. Codex CLI check
+  const codexExists = await commandExists('codex');
+  checks.push({
+    name: 'Codex CLI (secondary agent)',
+    category: 'AI Tooling',
+    ok: codexExists,
+    detail: codexExists ? 'Codex CLI available in PATH' : 'Codex CLI not found in PATH',
+    suggestion: codexExists ? undefined : 'Install Codex CLI if you want dual-agent orchestration'
+  });
+
+  // 6. Skills CLI check (skills.sh engine)
+  const skillsRes = await runExecutable('npx', ['-y', 'skills', '--version'], { silent: true });
+  checks.push({
+    name: 'Skills CLI (skills.sh engine)',
+    category: 'AI Tooling',
+    ok: skillsRes.ok,
+    version: skillsRes.stdout,
+    detail: skillsRes.ok ? `Functional (${skillsRes.stdout})` : 'Failed running npx skills',
+    suggestion: skillsRes.ok ? undefined : 'Check network connectivity or npm/npx configuration'
+  });
+
+  // 7. Project-level checks
+  checks.push({
+    name: `Project configuration (${path.basename(configPath)})`,
+    category: 'Project Config',
+    ok: !!projectConfig,
+    detail: projectConfig
+      ? `Preset: "${projectConfig.preset}" (v${projectConfig.schemaVersion || '1.0.0'}), pm: ${activePm}, agents: ${projectConfig.agents.primary}/${projectConfig.agents.secondary}`
+      : configError
+        ? `Invalid configuration: ${configError}`
+        : 'No aginit.config.json found in current directory',
+    suggestion: projectConfig
+      ? undefined
+      : configError
+        ? 'Correct the configuration fields before running initialization'
+        : 'Run `aginit init` to generate declarative configuration'
+  });
+
+  // 8. AGENTS.md check
+  const agentsPath = path.join(targetDir, 'AGENTS.md');
+  const agentsExists = fileExists(agentsPath);
+  const agentsContent = agentsExists ? readTextFile(agentsPath) || '' : '';
+  const hasIntakeSection = agentsContent.includes('Bootstrap & First Session');
+
+  checks.push({
+    name: 'AGENTS.md Context',
+    category: 'Project Config',
+    ok: agentsExists && hasIntakeSection,
+    detail: agentsExists
+      ? hasIntakeSection
+        ? 'AGENTS.md present with intake/bootstrap guidance'
+        : 'AGENTS.md present but missing intake guidance'
+      : 'AGENTS.md not found in directory',
+    suggestion: !agentsExists
+      ? 'Run `aginit init` to generate standard AGENTS.md'
+      : !hasIntakeSection
+        ? 'Run `aginit init` to add intake section to AGENTS.md'
+        : undefined
+  });
+
+  // 9. Installed skills check
+  const installedSkills = getInstalledSkills(targetDir);
+  checks.push({
+    name: 'Local Agent Skills (.agents/skills/)',
+    category: 'Project Config',
+    ok: installedSkills.length > 0,
+    detail:
+      installedSkills.length > 0
+        ? `${installedSkills.length} skills installed: ${installedSkills.join(', ')}`
+        : 'No skills found in .agents/skills/',
+    suggestion:
+      installedSkills.length === 0
+        ? 'Run `aginit init` or `npx skills add ...` to install skills'
+        : undefined
+  });
+
+  // Print grouped results
+  const categories: Array<'Environment' | 'AI Tooling' | 'Project Config'> = [
+    'Environment',
+    'AI Tooling',
+    'Project Config'
+  ];
+
+  for (const cat of categories) {
+    console.log(pc.bold(pc.underline(cat)));
+    const catChecks = checks.filter((c) => c.category === cat);
+    for (const c of catChecks) {
+      const icon = c.ok ? pc.green('✓') : pc.yellow('⚠');
+      const name = pc.bold(c.name);
+      console.log(`  ${icon} ${name}: ${c.detail}`);
+      if (c.suggestion) {
+        console.log(`    ${pc.cyan('→ Suggestion:')} ${pc.dim(c.suggestion)}`);
+      }
+    }
+    console.log();
+  }
+
+  const passed = checks.filter((c) => c.ok).length;
+  const total = checks.length;
+
+  if (passed === total) {
+    logger.success(pc.bold(`All ${total} health checks passed! System and repo are fully ready.`));
+  } else {
+    logger.info(`Doctor finished: ${passed}/${total} checks healthy.`);
+  }
+}

package/src/cli/init.ts

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import { readPackageManifest, readProjectConfig } from '../config/validation.js';
+import { createProject, NewProjectOptions } from './new.js';
+import { detectPackageManager } from '../adapters/package-manager.js';
+
+function sanitizeProjectName(rawName: string): string {
+  const sanitized = rawName
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9._-]/g, '')
+    .replace(/^[^a-z0-9]+/, '');
+  return sanitized || 'ai-project';
+}
+
+export async function initCurrentDirectory(options: NewProjectOptions = {}): Promise<boolean> {
+  const currentDir = process.cwd();
+  let projectName = path.basename(currentDir);
+
+  const saved = readProjectConfig(currentDir);
+  const pkg = readPackageManifest(currentDir);
+  if (pkg?.name) projectName = pkg.name;
+  else if (saved?.name) projectName = saved.name;
+  else projectName = sanitizeProjectName(projectName);
+
+  const packageManager =
+    options.packageManager ?? saved?.packageManager ?? detectPackageManager(currentDir) ?? 'pnpm';
+
+  return createProject(projectName, {
+    ...options,
+    packageManager,
+    targetDir: currentDir
+  });
+}

package/src/cli/main.ts

@@ -0,0 +1,191 @@
+import { Command } from 'commander';
+import { createProject } from './new.js';
+import { initCurrentDirectory } from './init.js';
+import { runDoctor } from './doctor.js';
+import { updateSkills } from '../adapters/skills.js';
+import { buildGraft } from '../adapters/graft.js';
+import { readProjectConfig } from '../config/validation.js';
+import { logger } from '../utils/logger.js';
+import { PresetType, WebFramework, PackageManager } from '../config/schema.js';
+import {
+  isInteractive,
+  promptNewProject,
+  promptInitProject,
+  runInteractiveWizard
+} from './wizard.js';
+
+export function createCliProgram(): Command {
+  const program = new Command();
+
+  program
+    .name('aginit')
+    .description(
+      'Minimal, modular AI-first project bootstrapper for T3 Code, Antigravity, and Codex'
+    )
+    .version('0.1.0');
+
+  // Root action: interactive wizard when in TTY, else display help
+  program.action(async () => {
+    if (isInteractive()) {
+      await runInteractiveWizard();
+    } else {
+      program.outputHelp();
+    }
+  });
+
+  // Command: new
+  program
+    .command('new [projectName]')
+    .description('Create a brand new AI-first project')
+    .option('-p, --preset <preset>', 'Project preset: web | cli | generic', 'generic')
+    .option('-f, --framework <framework>', 'Web framework: none | vite | next | existing', 'none')
+    .option('-m, --package-manager <pm>', 'Package manager: pnpm | npm | yarn | bun', 'pnpm')
+    .option(
+      '--spec-workflow',
+      'Include full spec and tickets skills (to-spec, to-tickets, implement-spec)'
+    )
+    .option('--no-skills', 'Skip installing AI skills')
+    .option('--no-graft', 'Skip codebase graph (Graft) setup')
+    .option('--no-git', 'Skip git repository initialization')
+    .option('--dry-run', 'Simulate creation without writing changes to disk')
+    .action(async (projectName: string | undefined, options: any, command: Command) => {
+      let finalName = projectName;
+      let finalPreset = options.preset;
+      let finalFramework = options.framework;
+      let finalPackageManager = options.packageManager;
+      let finalSpecWorkflow = options.specWorkflow;
+
+      if (!finalName) {
+        if (!isInteractive()) {
+          program.error("error: missing required argument 'projectName'");
+        }
+        const answers = await promptNewProject({
+          preset:
+            command.getOptionValueSource('preset') === 'cli'
+              ? (options.preset as PresetType)
+              : undefined,
+          framework:
+            command.getOptionValueSource('framework') === 'cli'
+              ? (options.framework as WebFramework)
+              : undefined,
+          packageManager:
+            command.getOptionValueSource('packageManager') === 'cli'
+              ? (options.packageManager as PackageManager)
+              : undefined,
+          specWorkflow:
+            command.getOptionValueSource('specWorkflow') === 'cli'
+              ? options.specWorkflow
+              : undefined
+        });
+        finalName = answers.projectName;
+        finalPreset = answers.preset;
+        finalFramework = answers.framework;
+        finalPackageManager = answers.packageManager;
+        finalSpecWorkflow = answers.specWorkflow;
+      }
+
+      const complete = await createProject(finalName, {
+        preset: finalPreset as PresetType,
+        framework: finalFramework as WebFramework,
+        packageManager: finalPackageManager as PackageManager,
+        specWorkflow: finalSpecWorkflow,
+        skills: options.skills,
+        graft: options.graft,
+        git: options.git,
+        dryRun: options.dryRun
+      });
+      if (!complete && !options.dryRun) process.exitCode = 1;
+    });
+
+  // Command: init
+  program
+    .command('init')
+    .description('Initialize or update AI-first capabilities in the current directory')
+    .option('-p, --preset <preset>', 'Project preset: web | cli | generic')
+    .option('-f, --framework <framework>', 'Web framework: none | vite | next | existing')
+    .option('-m, --package-manager <pm>', 'Package manager: pnpm | npm | yarn | bun')
+    .option(
+      '--spec-workflow',
+      'Include full spec and tickets skills (to-spec, to-tickets, implement-spec)'
+    )
+    .option('--no-skills', 'Skip installing AI skills')
+    .option('--no-graft', 'Skip codebase graph (Graft) setup')
+    .option('--no-git', 'Skip git repository initialization')
+    .option('--dry-run', 'Simulate setup without writing changes to disk')
+    .action(async (options: any, command: Command) => {
+      let finalPreset = options.preset;
+      let finalFramework = options.framework;
+      let finalPackageManager = options.packageManager;
+      let finalSpecWorkflow = options.specWorkflow;
+
+      const isPresetExplicit = command.getOptionValueSource('preset') === 'cli';
+      const isFrameworkExplicit = command.getOptionValueSource('framework') === 'cli';
+      const isPmExplicit = command.getOptionValueSource('packageManager') === 'cli';
+      const isSpecExplicit = command.getOptionValueSource('specWorkflow') === 'cli';
+
+      const savedConfig = readProjectConfig(process.cwd());
+      if (isInteractive() && !isPresetExplicit && !options.dryRun && !savedConfig) {
+        const answers = await promptInitProject({
+          preset: isPresetExplicit ? (options.preset as PresetType) : undefined,
+          framework: isFrameworkExplicit ? (options.framework as WebFramework) : undefined,
+          packageManager: isPmExplicit ? (options.packageManager as PackageManager) : undefined,
+          specWorkflow: isSpecExplicit ? options.specWorkflow : undefined
+        });
+        finalPreset = answers.preset;
+        finalFramework = answers.framework;
+        finalPackageManager = answers.packageManager;
+        finalSpecWorkflow = answers.specWorkflow;
+      }
+
+      const complete = await initCurrentDirectory({
+        preset: finalPreset as PresetType,
+        framework: finalFramework as WebFramework,
+        packageManager: finalPackageManager as PackageManager,
+        specWorkflow: finalSpecWorkflow,
+        skills: options.skills,
+        graft: options.graft,
+        git: options.git,
+        dryRun: options.dryRun
+      });
+      if (!complete && !options.dryRun) process.exitCode = 1;
+    });
+
+  // Command: doctor
+  program
+    .command('doctor')
+    .description('Run system and project diagnostics for AI agent readiness')
+    .option('-d, --dir <path>', 'Target directory to check', process.cwd())
+    .action(async (options: any) => {
+      await runDoctor(options.dir);
+    });
+
+  // Command: update
+  program
+    .command('update')
+    .description('Update installed skills and refresh codebase graph')
+    .option('--dry-run', 'Simulate update')
+    .action(async (options: any) => {
+      logger.banner('Aginit — Update');
+      const targetDir = process.cwd();
+      const config = readProjectConfig(targetDir);
+      const skillsOk =
+        config?.skills.sources.length === 0
+          ? true
+          : await updateSkills(targetDir, { dryRun: options.dryRun });
+      const graftOk =
+        config?.codebase.graft === false
+          ? true
+          : await buildGraft(targetDir, { dryRun: options.dryRun });
+      if (skillsOk && graftOk) logger.success('Update finished.');
+      else {
+        if (!skillsOk) logger.warn('Skills update failed. Check connectivity and the skills CLI.');
+        if (!graftOk)
+          logger.warn(
+            'Graft refresh failed or Graft is unavailable. Check installation and rerun graft build.'
+          );
+        process.exitCode = 1;
+      }
+    });
+
+  return program;
+}