@antomanc/aginit 0.1.0

package/src/config/validation.ts

@@ -0,0 +1,96 @@
+import path from 'node:path';
+import { fileExists, readJsonFile } from '../utils/fs.js';
+import { AginitConfig, AGINIT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME } from './schema.js';
+
+export const PRESETS = ['web', 'cli', 'generic'] as const;
+export const FRAMEWORKS = ['none', 'vite', 'next', 'existing'] as const;
+export const SUPPORTED_PACKAGE_MANAGERS = ['pnpm', 'npm', 'yarn', 'bun'] as const;
+export function isRecord(value: unknown): value is Record<string, any> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function validateProjectName(name: string): void {
+  if (!/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(name) || name.length > 214) {
+    throw new Error(
+      'Invalid project name. Use a lowercase npm package name (letters, numbers, dots, dashes, underscores; optional @scope/name).'
+    );
+  }
+}
+export function validateUpstreamArgument(value: unknown, label: string): asserts value is string {
+  if (
+    typeof value !== 'string' ||
+    !value.trim() ||
+    value.startsWith('-') ||
+    /[\x00-\x1f\x7f]/.test(value)
+  ) {
+    throw new Error(
+      `Invalid ${label}: expected a nonempty value that does not begin with an option.`
+    );
+  }
+}
+export function validateConfig(value: unknown): AginitConfig {
+  const fail = (field: string): never => {
+    throw new Error(`Invalid project configuration: ${field}`);
+  };
+  if (!isRecord(value)) return fail('expected a JSON object');
+  if (value.schemaVersion !== undefined && value.schemaVersion !== '1.0.0')
+    fail('unsupported schemaVersion');
+  if (typeof value.name !== 'string' || !value.name) fail('name');
+  if (!PRESETS.includes(value.preset)) fail('preset');
+  if (value.framework !== undefined && !FRAMEWORKS.includes(value.framework)) fail('framework');
+  if (
+    value.packageManager !== undefined &&
+    !SUPPORTED_PACKAGE_MANAGERS.includes(value.packageManager)
+  )
+    fail('packageManager');
+  if (!isRecord(value.agents)) fail('agents');
+  for (const key of ['primary', 'secondary'])
+    validateUpstreamArgument(value.agents[key], `agent ${key}`);
+  if (!isRecord(value.skills) || !Array.isArray(value.skills.sources)) fail('skills.sources');
+  if (value.skills.workflow !== undefined && !['minimal', 'spec'].includes(value.skills.workflow))
+    fail('skills.workflow');
+  for (const source of value.skills.sources) {
+    if (!isRecord(source) || !Array.isArray(source.skills)) fail('skill source');
+    validateUpstreamArgument(source.package, 'skill package');
+    for (const skill of source.skills) validateUpstreamArgument(skill, 'skill name');
+  }
+  for (const [section, keys] of Object.entries({
+    codebase: ['graft'],
+    browser: ['visualAgent', 'playwright'],
+    docs: ['adr'],
+    github: ['ci']
+  })) {
+    if (!isRecord(value[section])) fail(section);
+    for (const key of keys) if (typeof value[section][key] !== 'boolean') fail(`${section}.${key}`);
+  }
+  return { ...value, schemaVersion: '1.0.0' } as AginitConfig;
+}
+export function readProjectConfig(dir: string): AginitConfig | null {
+  const file = [AGINIT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME]
+    .map((name) => path.join(dir, name))
+    .find(fileExists);
+  if (!file) return null;
+  try {
+    return validateConfig(readJsonFile<unknown>(file));
+  } catch (error) {
+    throw new Error(
+      `${path.basename(file)}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+export function readPackageManifest(dir: string): Record<string, any> | null {
+  const file = path.join(dir, 'package.json');
+  if (!fileExists(file)) return null;
+  const pkg = readJsonFile<unknown>(file);
+  if (!isRecord(pkg)) throw new Error('Invalid package.json: expected a JSON object.');
+  for (const key of ['scripts', 'dependencies', 'devDependencies']) {
+    if (
+      pkg[key] !== undefined &&
+      (!isRecord(pkg[key]) || Object.values(pkg[key]).some((v) => typeof v !== 'string'))
+    ) {
+      throw new Error(`Invalid package.json: ${key} must contain string values.`);
+    }
+  }
+  if (pkg.name !== undefined && typeof pkg.name !== 'string')
+    throw new Error('Invalid package.json: name must be a string.');
+  return pkg;
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from './config/schema.js';
+export * from './config/defaults.js';
+export * from './config/validation.js';
+export * from './presets/registry.js';
+export * from './presets/types.js';
+export * from './adapters/package-manager.js';
+export * from './adapters/git.js';
+export * from './adapters/skills.js';
+export * from './adapters/graft.js';
+export * from './adapters/agents-md.js';
+export * from './adapters/browser.js';
+export * from './cli/new.js';
+export * from './cli/init.js';
+export * from './cli/doctor.js';
+export * from './cli/wizard.js';

package/src/presets/adr.ts

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import { safeWriteFile } from '../utils/fs.js';
+
+const ADR_0001_CONTENT = `# 1. Record Architecture Decisions
+
+Date: 2026-10-04
+
+## Status
+Accepted
+
+## Context
+We need to record significant architectural, structural, and tooling decisions
+made throughout the lifecycle of this project so humans and AI agents understand
+the rationale behind key choices.
+
+## Decision
+We will use Architecture Decision Records (ADRs) stored in \`docs/adr/\`.
+Each record describes:
+- **Status**: Proposed, Accepted, Rejected, Superseded.
+- **Context**: The problem or requirement prompting the decision.
+- **Decision**: The selected option and why it was chosen.
+- **Consequences**: Positive and negative outcomes or trade-offs.
+
+## Consequences
+- Every major architectural shift is tracked in version control.
+- Agents reading this repository can inspect historical decisions to avoid
+  re-proposing already evaluated or superseded designs.
+`;
+
+export function setupAdr(
+  targetDir: string,
+  options: { dryRun?: boolean; silent?: boolean } = {}
+): void {
+  const { dryRun = false, silent = false } = options;
+  const adrFile = path.join(targetDir, 'docs', 'adr', '0001-record-architecture-decisions.md');
+  safeWriteFile(adrFile, ADR_0001_CONTENT, { dryRun, silent });
+}

package/src/presets/cli.ts

@@ -0,0 +1,136 @@
+import path from 'node:path';
+import { fileExists, safeWriteFile, writeJsonFile } from '../utils/fs.js';
+import { PresetContext, PresetHandler } from './types.js';
+import { readPackageManifest } from '../config/validation.js';
+import { addTestingDependencies, setupTesting, VITEST_VERSION } from './testing.js';
+import { setupAdr } from './adr.js';
+
+export const cliPreset: PresetHandler = {
+  name: 'cli',
+  description: 'AI-first TypeScript CLI application with Commander, Picocolors, and Vitest',
+  async scaffold(ctx: PresetContext): Promise<void> {
+    const { targetDir, projectName, dryRun, silent } = ctx;
+    const pm = ctx.config.packageManager || 'pnpm';
+
+    const existing = readPackageManifest(targetDir);
+    if (existing) {
+      const hadVitestScript = Object.values(existing.scripts || {}).some(
+        (script) => typeof script === 'string' && /^vitest(?:\s|$)/.test(script)
+      );
+      addTestingDependencies(existing);
+      writeJsonFile(path.join(targetDir, 'package.json'), existing, {
+        overwrite: true,
+        dryRun,
+        silent
+      });
+      setupTesting(ctx, hadVitestScript);
+      if (ctx.config.docs.adr) setupAdr(targetDir, { dryRun, silent });
+      return;
+    }
+
+    // 1. package.json
+    const pkg = {
+      name: projectName,
+      version: '0.1.0',
+      type: 'module',
+      bin: {
+        [projectName.split('/').pop()!]: './bin/cli.js'
+      },
+      scripts: {
+        build: 'tsc',
+        test: 'vitest run',
+        'test:watch': 'vitest',
+        typecheck: 'tsc --noEmit',
+        prepack: 'tsc'
+      },
+      dependencies: {
+        commander: '^12.1.0',
+        picocolors: '^1.1.1'
+      },
+      devDependencies: {
+        '@types/node': '^22.8.0',
+        typescript: '^5.6.3',
+        vitest: VITEST_VERSION
+      }
+    };
+    writeJsonFile(path.join(targetDir, 'package.json'), pkg, { dryRun, silent });
+
+    // pnpm-workspace.yaml generated ONLY for pnpm!
+    if (pm === 'pnpm') {
+      const workspaceYamlPath = path.join(targetDir, 'pnpm-workspace.yaml');
+      if (!fileExists(workspaceYamlPath)) {
+        const workspaceYaml = `allowBuilds:\n  esbuild: true\n`;
+        safeWriteFile(workspaceYamlPath, workspaceYaml, { dryRun, silent });
+      }
+    }
+
+    // 2. tsconfig.json
+    const tsconfig = {
+      compilerOptions: {
+        target: 'ES2022',
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        lib: ['ES2022'],
+        strict: true,
+        skipLibCheck: true,
+        outDir: 'dist',
+        rootDir: 'src',
+        declaration: true
+      },
+      include: ['src/**/*']
+    };
+    writeJsonFile(path.join(targetDir, 'tsconfig.json'), tsconfig, { dryRun, silent });
+
+    // 3. vitest.config.ts
+    const vitestConfig = `import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.{js,ts}']
+  }
+});
+`;
+    safeWriteFile(path.join(targetDir, 'vitest.config.ts'), vitestConfig, { dryRun, silent });
+
+    // 4. Executable CLI entrypoint
+    const binCli = `#!/usr/bin/env node
+import { run } from '../dist/index.js';
+
+run(process.argv.slice(2)).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+`;
+    safeWriteFile(path.join(targetDir, 'bin', 'cli.js'), binCli, {
+      dryRun,
+      silent,
+      mode: 0o755
+    });
+
+    // 5. Source code
+    const srcIndex = `export async function run(args: string[] = []): Promise<void> {\n  console.log(${JSON.stringify(projectName + ' ready. Args:')}, args);\n}\n`;
+    const createdSource = safeWriteFile(path.join(targetDir, 'src', 'index.ts'), srcIndex, {
+      dryRun,
+      silent
+    });
+
+    // 6. Unit test
+    const unitTest = `import { describe, it, expect } from 'vitest';
+import { run } from '../src/index.js';
+
+describe('run', () => {
+  it('runs with the supplied arguments', async () => {
+    await expect(run(['--help'])).resolves.toBeUndefined();
+  });
+});
+`;
+    if (createdSource)
+      safeWriteFile(path.join(targetDir, 'tests', 'index.test.ts'), unitTest, { dryRun, silent });
+    else setupTesting(ctx);
+
+    // 7. Docs ADR
+    if (ctx.config.docs.adr) {
+      setupAdr(targetDir, { dryRun, silent });
+    }
+  }
+};

package/src/presets/generic.ts

@@ -0,0 +1,32 @@
+import path from 'node:path';
+import { fileExists, writeJsonFile } from '../utils/fs.js';
+import { PresetContext, PresetHandler } from './types.js';
+import { addTestingDependencies, setupTesting } from './testing.js';
+import { setupAdr } from './adr.js';
+
+export const genericPreset: PresetHandler = {
+  name: 'generic',
+  description: 'Minimal, unopinionated project skeleton with AI skills, Git, and ADR structure',
+  async scaffold(ctx: PresetContext): Promise<void> {
+    const { targetDir, projectName, dryRun, silent } = ctx;
+
+    const pkgPath = path.join(targetDir, 'package.json');
+    if (!fileExists(pkgPath)) {
+      const pkg = {
+        name: projectName,
+        version: '0.1.0',
+        type: 'module',
+        scripts: {
+          test: 'vitest run'
+        }
+      };
+      addTestingDependencies(pkg);
+      writeJsonFile(pkgPath, pkg, { dryRun, silent });
+      setupTesting(ctx);
+    }
+
+    if (ctx.config.docs.adr) {
+      setupAdr(targetDir, { dryRun, silent });
+    }
+  }
+};

package/src/presets/registry.ts

@@ -0,0 +1,24 @@
+import { PresetHandler } from './types.js';
+import { webPreset } from './web.js';
+import { cliPreset } from './cli.js';
+import { genericPreset } from './generic.js';
+import { PresetType } from '../config/schema.js';
+
+export const presets: Record<PresetType, PresetHandler> = {
+  web: webPreset,
+  cli: cliPreset,
+  generic: genericPreset
+};
+
+export function getPreset(name: string): PresetHandler {
+  const handler = presets[name as PresetType];
+  if (!handler) {
+    const valid = Object.keys(presets).join(', ');
+    throw new Error(`Unknown preset: "${name}". Valid presets are: ${valid}`);
+  }
+  return handler;
+}
+
+export function listPresets(): PresetHandler[] {
+  return Object.values(presets);
+}

package/src/presets/testing.ts

@@ -0,0 +1,56 @@
+import path from 'node:path';
+import { safeWriteFile, fileExists } from '../utils/fs.js';
+import { PresetContext } from './types.js';
+
+export const VITEST_VERSION = '^4.1.11';
+export function addTestingDependencies(pkg: Record<string, any>, playwright = false): void {
+  pkg.scripts ??= {};
+  pkg.devDependencies ??= {};
+  if (!pkg.dependencies?.vitest && !pkg.devDependencies.vitest)
+    pkg.devDependencies.vitest = VITEST_VERSION;
+  const customTest = pkg.scripts.test && !/^vitest(?:\s|$)/.test(pkg.scripts.test);
+  const testScript = customTest ? 'test:unit' : 'test';
+  pkg.scripts[testScript] ??= 'vitest run';
+  pkg.scripts[customTest ? 'test:unit:watch' : 'test:watch'] ??= 'vitest';
+  if (playwright) {
+    pkg.scripts['test:e2e'] ??= 'playwright test';
+    if (!pkg.dependencies?.['@playwright/test'] && !pkg.devDependencies['@playwright/test'])
+      pkg.devDependencies['@playwright/test'] = '^1.63.0';
+  }
+}
+
+/** A starter harness checks package metadata without assuming application exports. */
+export function setupTesting(ctx: PresetContext, preserveViteTestConfig = false): void {
+  const { targetDir, dryRun, silent } = ctx;
+  const hasConfig = [
+    'vitest.config.ts',
+    'vitest.config.js',
+    'vitest.config.mts',
+    'vitest.config.mjs',
+    'vitest.config.cts',
+    'vitest.config.cjs',
+    ...(preserveViteTestConfig
+      ? ['vite.config.ts', 'vite.config.js', 'vite.config.mts', 'vite.config.mjs']
+      : [])
+  ].some((name) => fileExists(path.join(targetDir, name)));
+  if (!hasConfig)
+    safeWriteFile(
+      path.join(targetDir, 'vitest.config.mts'),
+      `import { defineConfig } from 'vitest/config';\n\nexport default defineConfig({\n  test: { include: ['tests/**/*.test.{js,ts}'] }\n});\n`,
+      { dryRun, silent }
+    );
+  safeWriteFile(
+    path.join(targetDir, 'tests', 'aginit.test.js'),
+    `import { it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+
+// Starter harness: add application behavior tests as the project takes shape.
+it('has a valid project manifest', () => {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  expect(typeof pkg.name).toBe('string');
+  expect(pkg.name.length).toBeGreaterThan(0);
+});
+`,
+    { dryRun, silent }
+  );
+}

package/src/presets/types.ts

@@ -0,0 +1,15 @@
+import { AIProjectConfig, PresetType } from '../config/schema.js';
+
+export interface PresetContext {
+  targetDir: string;
+  projectName: string;
+  config: AIProjectConfig;
+  dryRun?: boolean;
+  silent?: boolean;
+}
+
+export interface PresetHandler {
+  name: PresetType;
+  description: string;
+  scaffold: (ctx: PresetContext) => Promise<void>;
+}

package/src/presets/web.ts

@@ -0,0 +1,99 @@
+import path from 'node:path';
+import { fileExists, safeWriteFile, writeJsonFile } from '../utils/fs.js';
+import { readPackageManifest } from '../config/validation.js';
+import { runExecutable } from '../utils/shell.js';
+import { PresetContext, PresetHandler } from './types.js';
+import { setupBrowserTesting } from '../adapters/browser.js';
+import { setupAdr } from './adr.js';
+import { scaffoldCommand } from '../adapters/package-manager.js';
+import { addTestingDependencies, setupTesting } from './testing.js';
+
+export const webPreset: PresetHandler = {
+  name: 'web',
+  description:
+    'Framework-agnostic web project with upstream scaffolding, Vitest and optional Playwright',
+  async scaffold(ctx: PresetContext): Promise<void> {
+    const { targetDir, projectName, dryRun, silent, config } = ctx;
+    const framework = config.framework || 'none';
+    const pkgPath = path.join(targetDir, 'package.json');
+    const pm = config.packageManager || 'pnpm';
+    let pkg = readPackageManifest(targetDir);
+    const fresh = pkg === null;
+    if (fresh && framework === 'existing')
+      throw new Error('An existing framework requires an existing package.json.');
+    if (fresh && (framework === 'vite' || framework === 'next')) {
+      const command = scaffoldCommand(pm, framework);
+      const result = await runExecutable(command.executable, command.args, {
+        cwd: targetDir,
+        dryRun,
+        silent: true
+      });
+      if (!result.ok)
+        throw new Error(`${framework} scaffolding failed: ${result.stderr || result.stdout}`);
+      if (!dryRun) {
+        pkg = readPackageManifest(targetDir);
+        const expected = framework === 'vite' ? 'index.html' : 'src/app/page.tsx';
+        if (!pkg || !fileExists(path.join(targetDir, expected)))
+          throw new Error(
+            `${framework} scaffolding did not create a complete project; it may have been cancelled.`
+          );
+      }
+    }
+    if (!pkg) {
+      // In a framework dry run the upstream command has only been displayed.
+      if (dryRun && (framework === 'vite' || framework === 'next')) return;
+      pkg = {
+        name: projectName,
+        version: '0.1.0',
+        type: 'module',
+        scripts: { build: 'tsc', typecheck: 'tsc --noEmit' },
+        devDependencies: { '@types/node': '^22.8.0', typescript: '^5.6.3' }
+      };
+    }
+    const hadVitestScript = Object.values(pkg.scripts || {}).some(
+      (script) => typeof script === 'string' && /^vitest(?:\s|$)/.test(script)
+    );
+    addTestingDependencies(pkg, config.browser.playwright);
+    if (fileExists(path.join(targetDir, 'tsconfig.json'))) {
+      pkg.scripts.typecheck ??=
+        fresh && framework === 'next' ? 'next typegen && tsc --noEmit' : 'tsc --noEmit';
+      if (!pkg.dependencies?.typescript && !pkg.devDependencies.typescript)
+        pkg.devDependencies.typescript = '^5.6.3';
+    }
+    // Only scaffold application source and compiler settings for a fresh agnostic project.
+    if (fresh && framework === 'none') {
+      writeJsonFile(
+        path.join(targetDir, 'tsconfig.json'),
+        {
+          compilerOptions: {
+            target: 'ES2022',
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            lib: ['ES2022', 'DOM'],
+            strict: true,
+            skipLibCheck: true,
+            outDir: 'dist',
+            rootDir: 'src'
+          },
+          include: ['src/**/*']
+        },
+        { dryRun, silent }
+      );
+      safeWriteFile(
+        path.join(targetDir, 'src', 'index.ts'),
+        `export function createApp() {\n  return { name: ${JSON.stringify(projectName)}, status: 'ready' };\n}\n`,
+        { dryRun, silent }
+      );
+    }
+    writeJsonFile(pkgPath, pkg, { overwrite: true, dryRun, silent });
+    if (pm === 'pnpm')
+      safeWriteFile(
+        path.join(targetDir, 'pnpm-workspace.yaml'),
+        'allowBuilds:\n  esbuild: true\n',
+        { dryRun, silent }
+      );
+    setupTesting(ctx, hadVitestScript);
+    if (config.browser.playwright) setupBrowserTesting(targetDir, { dryRun, silent });
+    if (config.docs.adr) setupAdr(targetDir, { dryRun, silent });
+  }
+};

package/src/utils/fs.ts

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from './logger.js';
+
+export interface WriteFileOptions {
+  overwrite?: boolean;
+  dryRun?: boolean;
+  silent?: boolean;
+  mode?: number;
+}
+
+export function ensureDir(dirPath: string, dryRun = false): void {
+  if (dryRun) {
+    logger.dim(`[dry-run] Would create directory: ${dirPath}`);
+    return;
+  }
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+export function fileExists(filePath: string): boolean {
+  return fs.existsSync(filePath);
+}
+
+export function safeWriteFile(
+  filePath: string,
+  content: string,
+  options: WriteFileOptions = {}
+): boolean {
+  const { overwrite = false, dryRun = false, silent = false, mode } = options;
+
+  if (fileExists(filePath) && !overwrite) {
+    if (!silent) {
+      logger.dim(`Skipping existing file: ${path.basename(filePath)}`);
+    }
+    return false;
+  }
+
+  if (dryRun) {
+    logger.dim(`[dry-run] Would write file: ${filePath}`);
+    return true;
+  }
+
+  ensureDir(path.dirname(filePath), false);
+  fs.writeFileSync(filePath, content, { encoding: 'utf-8', mode });
+  if (mode !== undefined && process.platform !== 'win32') {
+    try {
+      fs.chmodSync(filePath, mode);
+    } catch {
+      // ignore in environments that do not permit chmod
+    }
+  }
+  return true;
+}
+
+export function readTextFile(filePath: string): string | null {
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, 'utf-8');
+}
+
+export function readJsonFile<T>(filePath: string): T | null {
+  const text = readTextFile(filePath);
+  if (!text) return null;
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    return null;
+  }
+}
+
+export function writeJsonFile(
+  filePath: string,
+  data: unknown,
+  options: WriteFileOptions = {}
+): boolean {
+  const content = JSON.stringify(data, null, 2) + '\n';
+  return safeWriteFile(filePath, content, options);
+}

package/src/utils/logger.ts

@@ -0,0 +1,20 @@
+import pc from 'picocolors';
+
+export const logger = {
+  info: (msg: string) => console.log(pc.cyan('ℹ ') + msg),
+  success: (msg: string) => console.log(pc.green('✓ ') + msg),
+  warn: (msg: string) => console.log(pc.yellow('⚠ ') + msg),
+  error: (msg: string) => console.error(pc.red('✖ ') + msg),
+  dim: (msg: string) => console.log(pc.dim(msg)),
+  step: (step: number, total: number, msg: string) => {
+    console.log(pc.bold(pc.magenta(`[${step}/${total}] `)) + pc.bold(msg));
+  },
+  banner: (title: string, subtitle?: string) => {
+    console.log();
+    console.log(pc.bold(pc.cyan(title)));
+    if (subtitle) {
+      console.log(pc.dim(subtitle));
+    }
+    console.log();
+  }
+};