buildline 0.0.0-stage → 0.3.0

package/src/detect.js

@@ -0,0 +1,228 @@
+// Inspects a project directory and reports what is there: language, framework,
+// package manager, and the commands the factory should use as quality gates.
+// Everything is best-effort and read-only; unknown values stay null.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const exists = (dir, f) => fs.existsSync(path.join(dir, f));
+const readJson = (file) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+};
+const readText = (file) => {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+};
+
+const IGNORED = new Set(['.git', 'node_modules', '.DS_Store', '.buildline', '.claude', '.idea', '.vscode']);
+
+export function isEmptyProject(dir) {
+  if (!fs.existsSync(dir)) return true;
+  const entries = fs.readdirSync(dir).filter((e) => !IGNORED.has(e));
+  const meaningful = entries.filter((e) => !/^(readme|license|\.gitignore|\.env)/i.test(e));
+  return meaningful.length === 0;
+}
+
+function detectNode(dir, stack) {
+  const pkg = readJson(path.join(dir, 'package.json'));
+  if (!pkg) return;
+  stack.languages.push(exists(dir, 'tsconfig.json') ? 'TypeScript' : 'JavaScript');
+
+  stack.packageManager = exists(dir, 'pnpm-lock.yaml')
+    ? 'pnpm'
+    : exists(dir, 'yarn.lock')
+      ? 'yarn'
+      : exists(dir, 'bun.lockb') || exists(dir, 'bun.lock')
+        ? 'bun'
+        : 'npm';
+  const run = stack.packageManager === 'npm' ? 'npm run' : stack.packageManager;
+
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const frameworks = [
+    ['next', 'Next.js'],
+    ['nuxt', 'Nuxt'],
+    ['@remix-run/react', 'Remix'],
+    ['@sveltejs/kit', 'SvelteKit'],
+    ['astro', 'Astro'],
+    ['@angular/core', 'Angular'],
+    ['vue', 'Vue'],
+    ['svelte', 'Svelte'],
+    ['solid-js', 'Solid'],
+    ['react-native', 'React Native'],
+    ['expo', 'Expo'],
+    ['electron', 'Electron'],
+    ['react', 'React'],
+    ['@nestjs/core', 'NestJS'],
+    ['express', 'Express'],
+    ['fastify', 'Fastify'],
+    ['hono', 'Hono'],
+  ];
+  for (const [dep, name] of frameworks) if (deps[dep]) stack.frameworks.push(name);
+  // "React" is implied by Next/Remix/React Native; keep the list readable.
+  if (stack.frameworks.some((f) => ['Next.js', 'Remix', 'React Native', 'Expo'].includes(f))) {
+    stack.frameworks = stack.frameworks.filter((f) => f !== 'React');
+  }
+
+  const ui = [
+    ['tailwindcss', 'Tailwind CSS'],
+    ['@mui/material', 'MUI'],
+    ['@chakra-ui/react', 'Chakra UI'],
+    ['@radix-ui/react-slot', 'Radix / shadcn'],
+    ['styled-components', 'styled-components'],
+  ];
+  for (const [dep, name] of ui) if (deps[dep]) stack.ui.push(name);
+  if (exists(dir, 'components.json')) stack.ui.push('shadcn/ui');
+  stack.ui = [...new Set(stack.ui)];
+
+  const s = pkg.scripts || {};
+  if (s.test && !/no test specified/.test(s.test)) stack.commands.test = `${run} test`;
+  if (s.lint) stack.commands.lint = `${run} lint`;
+  if (s.typecheck) stack.commands.typecheck = `${run} typecheck`;
+  else if (s['type-check']) stack.commands.typecheck = `${run} type-check`;
+  else if (exists(dir, 'tsconfig.json')) stack.commands.typecheck = 'npx tsc --noEmit';
+  if (s.build) stack.commands.build = `${run} build`;
+  if (s.dev) stack.commands.dev = `${run} dev`;
+  else if (s.start) stack.commands.dev = `${run} start`;
+
+  if (deps.vitest) stack.testing.push('Vitest');
+  if (deps.jest) stack.testing.push('Jest');
+  if (deps['@playwright/test']) stack.testing.push('Playwright');
+  if (deps.cypress) stack.testing.push('Cypress');
+  if (deps['@storybook/react'] || deps.storybook) stack.testing.push('Storybook');
+
+  if (pkg.workspaces || exists(dir, 'pnpm-workspace.yaml') || exists(dir, 'turbo.json') || exists(dir, 'nx.json')) {
+    stack.monorepo = true;
+  }
+}
+
+function detectPython(dir, stack) {
+  const pyproject = readText(path.join(dir, 'pyproject.toml'));
+  const reqs = readText(path.join(dir, 'requirements.txt'));
+  if (!pyproject && !reqs && !exists(dir, 'setup.py')) return;
+  stack.languages.push('Python');
+  const all = (pyproject + '\n' + reqs).toLowerCase();
+  stack.packageManager ??= exists(dir, 'uv.lock') ? 'uv' : exists(dir, 'poetry.lock') ? 'poetry' : 'pip';
+  for (const [dep, name] of [
+    ['django', 'Django'],
+    ['fastapi', 'FastAPI'],
+    ['flask', 'Flask'],
+    ['streamlit', 'Streamlit'],
+  ]) {
+    if (all.includes(dep)) stack.frameworks.push(name);
+  }
+  const prefix = stack.packageManager === 'uv' ? 'uv run ' : stack.packageManager === 'poetry' ? 'poetry run ' : '';
+  if (all.includes('pytest') || exists(dir, 'tests')) stack.commands.test ??= `${prefix}pytest`;
+  if (all.includes('ruff')) stack.commands.lint ??= `${prefix}ruff check .`;
+  if (all.includes('mypy')) stack.commands.typecheck ??= `${prefix}mypy .`;
+}
+
+function detectOthers(dir, stack) {
+  if (exists(dir, 'go.mod')) {
+    stack.languages.push('Go');
+    stack.commands.test ??= 'go test ./...';
+    stack.commands.lint ??= 'go vet ./...';
+    stack.commands.build ??= 'go build ./...';
+  }
+  if (exists(dir, 'Cargo.toml')) {
+    stack.languages.push('Rust');
+    stack.commands.test ??= 'cargo test';
+    stack.commands.lint ??= 'cargo clippy -- -D warnings';
+    stack.commands.build ??= 'cargo build';
+  }
+  if (exists(dir, 'Gemfile')) {
+    stack.languages.push('Ruby');
+    if (readText(path.join(dir, 'Gemfile')).includes('rails')) stack.frameworks.push('Rails');
+    stack.commands.test ??= exists(dir, 'spec') ? 'bundle exec rspec' : 'bin/rails test';
+  }
+  if (exists(dir, 'composer.json')) {
+    stack.languages.push('PHP');
+    if (exists(dir, 'artisan')) stack.frameworks.push('Laravel');
+    stack.commands.test ??= exists(dir, 'artisan') ? 'php artisan test' : 'vendor/bin/phpunit';
+  }
+  if (exists(dir, 'pom.xml')) {
+    stack.languages.push('Java');
+    stack.commands.test ??= 'mvn test';
+  }
+  if (exists(dir, 'build.gradle') || exists(dir, 'build.gradle.kts')) {
+    stack.languages.push(exists(dir, 'build.gradle.kts') ? 'Kotlin' : 'Java');
+    stack.commands.test ??= './gradlew test';
+  }
+  if (fs.existsSync(dir) && fs.readdirSync(dir).some((f) => f.endsWith('.csproj') || f.endsWith('.sln'))) {
+    stack.languages.push('C#');
+    stack.frameworks.push('.NET');
+    stack.commands.test ??= 'dotnet test';
+  }
+  if (exists(dir, 'pubspec.yaml')) {
+    stack.languages.push('Dart');
+    stack.frameworks.push('Flutter');
+    stack.commands.test ??= 'flutter test';
+  }
+  if (fs.existsSync(dir) && fs.readdirSync(dir).some((f) => f.endsWith('.xcodeproj') || f === 'Package.swift')) {
+    stack.languages.push('Swift');
+  }
+}
+
+function detectTooling(dir, stack) {
+  const agents = [
+    ['CLAUDE.md', 'Claude Code'],
+    ['.claude', 'Claude Code'],
+    ['AGENTS.md', 'AGENTS.md'],
+    ['.cursor', 'Cursor'],
+    ['.cursorrules', 'Cursor'],
+    ['GEMINI.md', 'Gemini CLI'],
+    ['.github/copilot-instructions.md', 'GitHub Copilot'],
+    ['.windsurfrules', 'Windsurf'],
+    ['.kiro', 'Kiro'],
+    ['.specify', 'Spec Kit'],
+    ['.bmad-core', 'BMAD'],
+    ['_bmad', 'BMAD'],
+  ];
+  for (const [f, name] of agents) if (exists(dir, f)) stack.existingAgentConfig.push(name);
+  stack.existingAgentConfig = [...new Set(stack.existingAgentConfig)];
+  stack.git = exists(dir, '.git');
+  stack.ci = exists(dir, '.github/workflows') ? 'GitHub Actions' : exists(dir, '.gitlab-ci.yml') ? 'GitLab CI' : null;
+  stack.docker = exists(dir, 'Dockerfile') || exists(dir, 'docker-compose.yml') || exists(dir, 'compose.yaml');
+}
+
+export function detect(dir) {
+  const stack = {
+    empty: isEmptyProject(dir),
+    name: path.basename(path.resolve(dir)),
+    languages: [],
+    frameworks: [],
+    ui: [],
+    testing: [],
+    packageManager: null,
+    monorepo: false,
+    commands: { test: null, lint: null, typecheck: null, build: null, dev: null },
+    existingAgentConfig: [],
+    git: false,
+    ci: null,
+    docker: false,
+  };
+  if (stack.empty) {
+    detectTooling(dir, stack);
+    return stack;
+  }
+  const pkg = readJson(path.join(dir, 'package.json'));
+  if (pkg?.name) stack.name = pkg.name;
+  detectNode(dir, stack);
+  detectPython(dir, stack);
+  detectOthers(dir, stack);
+  detectTooling(dir, stack);
+  stack.languages = [...new Set(stack.languages)];
+  stack.frameworks = [...new Set(stack.frameworks)];
+  return stack;
+}
+
+export function describeStack(stack) {
+  if (stack.empty) return 'Empty project (greenfield)';
+  const parts = [...stack.frameworks, ...stack.languages.filter((l) => !stack.frameworks.length || l !== 'JavaScript')];
+  return parts.length ? parts.join(' · ') : 'Unknown stack';
+}

package/src/features.js

@@ -0,0 +1,157 @@
+// Reading and writing factory features (.buildline/features/<id>-<slug>/).
+// The CLI, the web dashboard and agents all share this on-disk format.
+import fs from 'node:fs';
+import path from 'node:path';
+import { render, templatesDir } from './render.js';
+
+export const STATIONS = ['new', 'spec', 'design', 'plan', 'build', 'verify', 'review', 'ship', 'done'];
+export const TYPES = ['fix', 'feature', 'epic'];
+export const APPROVAL_STAGES = ['spec', 'design', 'plan'];
+
+export const featuresDir = (root) => path.join(root, '.buildline', 'features');
+const today = () => new Date().toISOString().slice(0, 10);
+const now = () => new Date().toISOString();
+
+export function slugify(title) {
+  return (
+    title
+      .toLowerCase()
+      .normalize('NFKD')
+      .replace(/[̀-ͯ]/g, '')
+      .replace(/[^a-z0-9]+/g, ' ')
+      .trim()
+      .split(/\s+/)
+      .slice(0, 5)
+      .join('-') || 'feature'
+  );
+}
+
+export function listFeatures(root) {
+  const dir = featuresDir(root);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((d) => /^\d{3,}-/.test(d) && fs.existsSync(path.join(dir, d, 'feature.json')))
+    .sort()
+    .map((d) => {
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(dir, d, 'feature.json'), 'utf8'));
+        return { ...data, dir: d, path: path.join(dir, d) };
+      } catch (err) {
+        return { id: d.split('-')[0], dir: d, title: d, status: 'unknown', error: err.message, path: path.join(dir, d) };
+      }
+    });
+}
+
+export function findFeature(root, ref) {
+  const all = listFeatures(root);
+  if (!ref) return null;
+  const r = String(ref).toLowerCase();
+  return (
+    all.find((f) => f.id === r || f.id === r.padStart(3, '0')) ||
+    all.find((f) => f.dir === r) ||
+    all.find((f) => f.slug === r) ||
+    all.find((f) => f.dir.includes(r)) ||
+    null
+  );
+}
+
+export function saveFeature(feature) {
+  const { dir, path: p, error, ...data } = feature;
+  data.updated = now();
+  fs.writeFileSync(path.join(p, 'feature.json'), JSON.stringify(data, null, 2) + '\n');
+  return feature;
+}
+
+export function createFeature(root, { title, type = 'feature', owner = null, parent = null }) {
+  if (!title?.trim()) throw new Error('A feature needs a title.');
+  if (!TYPES.includes(type)) throw new Error(`Type must be one of: ${TYPES.join(', ')}`);
+  const existing = listFeatures(root);
+  const next = existing.reduce((m, f) => Math.max(m, parseInt(f.id, 10) || 0), 0) + 1;
+  const id = String(next).padStart(3, '0');
+  const slug = slugify(title);
+  const dir = path.join(featuresDir(root), `${id}-${slug}`);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const vars = { id, title: title.trim(), type, date: today() };
+  const feature = {
+    id,
+    slug,
+    title: title.trim(),
+    type,
+    status: type === 'fix' ? 'build' : 'spec',
+    owner,
+    parent,
+    blocked: null,
+    approvals: {},
+    tasks: [],
+    metrics: { reworks: 0, createdAt: now(), shippedAt: null },
+    history: [{ at: now(), station: 'new', note: `Opened as ${type}` }],
+    created: now(),
+    updated: now(),
+  };
+  fs.writeFileSync(path.join(dir, 'feature.json'), JSON.stringify(feature, null, 2) + '\n');
+  // Prefer the project's own (possibly customised) templates over the bundled ones.
+  for (const name of ['spec.md', 'progress.md']) {
+    const local = path.join(root, '.buildline', 'templates', name);
+    const source = fs.existsSync(local) ? local : path.join(templatesDir, 'feature', name);
+    fs.writeFileSync(path.join(dir, name), render(fs.readFileSync(source, 'utf8'), vars));
+  }
+  return { ...feature, dir: `${id}-${slug}`, path: dir };
+}
+
+export function setStatus(feature, status, note) {
+  if (!STATIONS.includes(status)) throw new Error(`Status must be one of: ${STATIONS.join(', ')}`);
+  feature.status = status;
+  if (status === 'done') feature.metrics = { ...feature.metrics, shippedAt: now() };
+  feature.history = [...(feature.history || []), { at: now(), station: status, note: note || `Moved to ${status}` }];
+  return saveFeature(feature);
+}
+
+export function approve(feature, stage, by) {
+  if (!APPROVAL_STAGES.includes(stage)) throw new Error(`Approval stage must be one of: ${APPROVAL_STAGES.join(', ')}`);
+  feature.approvals = { ...feature.approvals, [stage]: { by: by || 'unknown', at: now() } };
+  feature.history = [...(feature.history || []), { at: now(), station: stage, note: `${stage} approved by ${by || 'unknown'}` }];
+  return saveFeature(feature);
+}
+
+/** What a feature is waiting on, in plain words, for status displays. */
+export function nextAction(feature, autonomy = 2) {
+  const a = feature.approvals || {};
+  const tasks = feature.tasks || [];
+  const passing = tasks.filter((t) => t.passes).length;
+  if (feature.blocked) return { who: 'human', text: `blocked: ${feature.blocked}` };
+  switch (feature.status) {
+    case 'spec':
+      if (/TODO/.test(readSpecSection(feature, 'Acceptance') || 'TODO')) return { who: 'pm', text: 'needs requirements & acceptance', cmd: `/buildline-spec ${feature.id}` };
+      return autonomy <= 3 && !a.spec ? { who: 'pm', text: 'waiting on spec approval', cmd: `buildline approve ${feature.id} spec` } : { who: 'agent', text: 'ready for design', cmd: `/buildline-design ${feature.id}` };
+    case 'design':
+      return { who: 'designer', text: 'needs UX / technical design', cmd: `/buildline-design ${feature.id}` };
+    case 'plan':
+      return { who: 'eng', text: 'needs a task plan', cmd: `/buildline-plan ${feature.id}` };
+    case 'build':
+      if (feature.type !== 'fix' && autonomy <= 3 && !a.spec) return { who: 'pm', text: 'waiting on spec approval', cmd: `buildline approve ${feature.id} spec` };
+      if (feature.type !== 'fix' && autonomy <= 2 && !a.plan && tasks.length) return { who: 'eng', text: 'waiting on plan approval', cmd: `buildline approve ${feature.id} plan` };
+      return { who: 'agent', text: tasks.length ? `${passing}/${tasks.length} tasks passing` : 'ready to build', cmd: autonomy >= 3 ? `buildline run ${feature.id}` : `/buildline-build ${feature.id}` };
+    case 'verify':
+      return { who: 'agent', text: 'ready for verification', cmd: `/buildline-verify ${feature.id}` };
+    case 'review':
+      return { who: 'agent', text: 'ready for review', cmd: `/buildline-review ${feature.id}` };
+    case 'ship':
+      return { who: 'eng', text: 'ready to ship: open PR', cmd: `/buildline-ship ${feature.id}` };
+    case 'done':
+      return { who: null, text: 'shipped' };
+    default:
+      return { who: null, text: feature.status };
+  }
+}
+
+export function readSpecSection(feature, heading) {
+  try {
+    const text = fs.readFileSync(path.join(feature.path, 'spec.md'), 'utf8');
+    const m = new RegExp(`^## ${heading}\\s*$([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm').exec(text);
+    return m ? m[1].trim() : null;
+  } catch {
+    return null;
+  }
+}

package/src/files.js

@@ -0,0 +1,107 @@
+// Safe file writing for installs into projects that may already be running.
+//
+// Two write modes:
+//   - "file":  the factory owns the whole file. On update we only overwrite it
+//              if the user has not edited it since we wrote it (hash check).
+//   - "block": the file belongs to the user (AGENTS.md, CLAUDE.md, .gitignore).
+//              We only ever touch the region between our markers.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const MANIFEST = '.buildline/manifest.json';
+const START = (c) => `${c[0]} buildline:start — managed by buildline, edit outside this block ${c[1]}`.trim();
+const END = (c) => `${c[0]} buildline:end ${c[1]}`.trim();
+const COMMENT = { md: ['<!--', '-->'], hash: ['#', ''] };
+
+export const hash = (s) => crypto.createHash('sha256').update(s).digest('hex').slice(0, 16);
+
+export function loadManifest(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, MANIFEST), 'utf8'));
+  } catch {
+    return { version: null, files: {} };
+  }
+}
+
+export function saveManifest(root, manifest) {
+  const file = path.join(root, MANIFEST);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(manifest, null, 2) + '\n');
+}
+
+function blockRegex(style) {
+  const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const c = COMMENT[style];
+  return new RegExp(`${esc(c[0])} buildline:start[^\\n]*\\n[\\s\\S]*?${esc(END(c))}\\n?`);
+}
+
+/**
+ * Plan a single write without touching disk. Returns
+ * { rel, action: 'create'|'update'|'skip-modified'|'unchanged'|'merge', content }.
+ */
+export function planWrite(root, manifest, entry, { force = false } = {}) {
+  const abs = path.join(root, entry.path);
+  const exists = fs.existsSync(abs);
+  const current = exists ? fs.readFileSync(abs, 'utf8') : null;
+
+  if (entry.mode === 'block') {
+    const style = entry.comment || 'md';
+    const c = COMMENT[style];
+    const block = `${START(c)}\n${entry.content.trimEnd()}\n${END(c)}\n`;
+    if (!exists) {
+      const content = (entry.header ? entry.header + '\n\n' : '') + block;
+      return { rel: entry.path, action: 'create', content, record: block };
+    }
+    const re = blockRegex(style);
+    const next = re.test(current)
+      ? current.replace(re, block)
+      : entry.position === 'top'
+        ? block + '\n' + current
+        : current.trimEnd() + '\n\n' + block;
+    if (next === current) return { rel: entry.path, action: 'unchanged' };
+    return { rel: entry.path, action: re.test(current) ? 'update' : 'merge', content: next, record: block };
+  }
+
+  // Whole-file mode.
+  if (!exists) return { rel: entry.path, action: 'create', content: entry.content, record: entry.content };
+  // User-owned files (config, context, principles) are seeded once and then belong to the user.
+  if (entry.userOwned || current === entry.content) return { rel: entry.path, action: 'unchanged' };
+  const known = manifest.files[entry.path];
+  const untouched = known && known === hash(current);
+  if (!untouched && !force) return { rel: entry.path, action: 'skip-modified' };
+  return { rel: entry.path, action: 'update', content: entry.content, record: entry.content };
+}
+
+export function applyPlan(root, manifest, plans) {
+  for (const p of plans) {
+    if (p.content === undefined) continue;
+    const abs = path.join(root, p.rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, p.content);
+    if (p.executable) fs.chmodSync(abs, 0o755);
+    // For block files we record the block hash; whole files record the file hash.
+    manifest.files[p.rel] = hash(p.mode === 'block' ? p.record : p.content);
+  }
+}
+
+/** Remove our blocks and owned files. User-modified files are left alone. */
+export function planRemove(root, manifest, entries) {
+  const out = [];
+  for (const e of entries) {
+    const abs = path.join(root, e.path);
+    if (!fs.existsSync(abs)) continue;
+    const current = fs.readFileSync(abs, 'utf8');
+    if (e.mode === 'block') {
+      const next = current.replace(blockRegex(e.comment || 'md'), '').replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '');
+      out.push({ rel: e.path, action: next.trim() ? 'strip-block' : 'delete', content: next });
+    } else if (e.userOwned) {
+      out.push({ rel: e.path, action: 'keep-user' });
+    } else if (manifest.files[e.path] === hash(current)) {
+      out.push({ rel: e.path, action: 'delete' });
+    } else {
+      out.push({ rel: e.path, action: 'keep-modified' });
+    }
+  }
+  return out;
+}