soloship 0.1.0

package/dist/ci.js

@@ -0,0 +1,184 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export async function installCi(root, project) {
+    const results = [];
+    // Only install CI for projects with git and tests
+    if (!project.hasGit) {
+        results.push("CI: skipped (no git repository)");
+        return results;
+    }
+    const workflowsDir = join(root, ".github", "workflows");
+    // Don't overwrite existing CI
+    if (existsSync(workflowsDir)) {
+        results.push("CI: .github/workflows/ already exists, skipping");
+        return results;
+    }
+    mkdirSync(workflowsDir, { recursive: true });
+    // Main CI workflow
+    const ciWorkflow = generateCiWorkflow(project);
+    writeFileSync(join(workflowsDir, "ci.yml"), ciWorkflow);
+    results.push("CI: .github/workflows/ci.yml (lint, test, build on push)");
+    // Architecture fitness functions (only for TypeScript projects)
+    if (project.stack.language === "typescript" ||
+        project.stack.language === "javascript") {
+        const archTest = generateArchitectureTest(project);
+        const testDir = join(root, "__arch__");
+        if (!existsSync(testDir)) {
+            mkdirSync(testDir, { recursive: true });
+        }
+        writeFileSync(join(testDir, "fitness.test.ts"), archTest);
+        results.push("CI: __arch__/fitness.test.ts (architecture fitness functions)");
+    }
+    return results;
+}
+function generateCiWorkflow(project) {
+    const pm = project.stack.packageManager;
+    const installCmd = pm === "bun"
+        ? "bun install"
+        : pm === "pnpm"
+            ? "pnpm install"
+            : pm === "yarn"
+                ? "yarn install"
+                : "npm ci";
+    const nodeVersion = "22";
+    return `name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '${nodeVersion}'
+          cache: '${pm === "bun" ? "npm" : pm}'
+
+      - name: Install dependencies
+        run: ${installCmd}
+
+      - name: Lint
+        run: ${pm === "bun" ? "bun run lint" : "npm run lint"}
+        continue-on-error: false
+
+      - name: Test
+        run: ${pm === "bun" ? "bun test" : "npm test"}
+
+      - name: Build
+        run: ${pm === "bun" ? "bun run build" : "npm run build"}
+
+      - name: Security scan (Semgrep)
+        run: |
+          if [ -f ".semgrep.yml" ]; then
+            pip install semgrep
+            semgrep --config .semgrep.yml --error --severity ERROR src/
+            semgrep --config .semgrep.yml --severity WARNING src/ || true
+          fi
+
+      - name: Architecture fitness
+        run: npx vitest run __arch__/ 2>/dev/null || npx jest __arch__/ 2>/dev/null || true
+`;
+}
+function generateArchitectureTest(project) {
+    // Generate basic fitness functions based on common patterns
+    return `/**
+ * Architecture Fitness Functions
+ *
+ * These tests enforce architectural boundaries. They run in CI and fail
+ * the build if the architecture drifts from its blueprint.
+ *
+ * Customize these rules based on your project's module boundaries.
+ * Run /audit to discover what rules should be added.
+ */
+
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { describe, test, expect } from "vitest";
+
+const ROOT = resolve(__dirname, "..");
+
+function getSourceFiles(dir: string, ext = ".ts"): string[] {
+  const results: string[] = [];
+  if (!existsSync(dir)) return results;
+
+  function walk(d: string) {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name);
+      if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+        walk(full);
+      } else if (entry.isFile() && (entry.name.endsWith(ext) || entry.name.endsWith(ext + "x"))) {
+        results.push(full);
+      }
+    }
+  }
+  walk(dir);
+  return results;
+}
+
+function getImports(filePath: string): string[] {
+  const content = readFileSync(filePath, "utf-8");
+  const imports: string[] = [];
+  const importRegex = /(?:import|from)\\s+['"](.*?)['"]/g;
+  let match;
+  while ((match = importRegex.exec(content)) !== null) {
+    imports.push(match[1]);
+  }
+  return imports;
+}
+
+describe("Architecture Fitness Functions", () => {
+  test("no circular directory dependencies at top level", () => {
+    // This is a placeholder — customize based on your project structure.
+    // Example: src/pages/ should not import from src/components/
+    // if components/ imports from pages/ (circular).
+    expect(true).toBe(true);
+  });
+
+  test("CLAUDE.md exists", () => {
+    expect(existsSync(join(ROOT, "CLAUDE.md"))).toBe(true);
+  });
+
+  test("CHANGELOG.md exists", () => {
+    expect(existsSync(join(ROOT, "CHANGELOG.md"))).toBe(true);
+  });
+
+  test("no source file exceeds 500 lines", () => {
+    const srcDir = join(ROOT, "src");
+    if (!existsSync(srcDir)) return;
+
+    const violations: string[] = [];
+    for (const file of getSourceFiles(srcDir)) {
+      const lines = readFileSync(file, "utf-8").split("\\n").length;
+      if (lines > 500) {
+        violations.push(\`\${file.replace(ROOT + "/", "")} (\${lines} lines)\`);
+      }
+    }
+
+    expect(violations).toEqual([]);
+  });
+
+  test("no hardcoded API keys in source", () => {
+    const srcDir = join(ROOT, "src");
+    if (!existsSync(srcDir)) return;
+
+    const keyPattern = /(ANTHROPIC|OPENAI|STRIPE|FIREBASE)_[A-Z_]*KEY\\s*=\\s*["'][a-zA-Z0-9]{20,}["']/;
+    const violations: string[] = [];
+
+    for (const file of getSourceFiles(srcDir)) {
+      const content = readFileSync(file, "utf-8");
+      if (keyPattern.test(content)) {
+        violations.push(file.replace(ROOT + "/", ""));
+      }
+    }
+
+    expect(violations).toEqual([]);
+  });
+});
+`;
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,63 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { runInit } from "./init.js";
+import { runRollback } from "./rollback.js";
+import { runDoctor } from "./doctor.js";
+const program = new Command();
+program
+    .name("soloship")
+    .description("Ship solo, safely — guardrails for AI-assisted development")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("Initialize Soloship in the current project")
+    .option("--skip-prompts", "Use defaults without asking questions")
+    .action(async (options) => {
+    console.log("");
+    console.log(chalk.bold("Soloship") + " — Ship Solo, Safely");
+    console.log(chalk.dim("Setting up mechanical enforcement, documentation infrastructure, and workflow rules."));
+    console.log("");
+    try {
+        await runInit(options);
+        console.log("");
+        console.log(chalk.green.bold("Soloship initialized."));
+        console.log("");
+        console.log("Next steps:");
+        console.log(chalk.dim("  Existing project: ") + "Run /audit in Claude Code");
+        console.log(chalk.dim("  New project:      ") + "Run /bootstrap in Claude Code");
+        console.log("");
+    }
+    catch (err) {
+        console.error(chalk.red("Setup failed:"), err);
+        process.exit(1);
+    }
+});
+program
+    .command("rollback")
+    .description("Roll back to the last Soloship safety snapshot")
+    .action(async () => {
+    try {
+        await runRollback();
+    }
+    catch (err) {
+        console.error(chalk.red("Rollback failed:"), err);
+        process.exit(1);
+    }
+});
+program
+    .command("doctor")
+    .description("Audit your Claude Code environment for Soloship companion dependencies")
+    .action(async () => {
+    console.log("");
+    console.log(chalk.bold("Soloship Doctor"));
+    console.log(chalk.dim("Checking plugins, MCP servers, global skills, and hooks against the Soloship manifest."));
+    console.log("");
+    try {
+        await runDoctor();
+    }
+    catch (err) {
+        console.error(chalk.red("Doctor failed:"), err);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/detect.d.ts

@@ -0,0 +1,30 @@
+export interface ProjectInfo {
+    name: string;
+    description: string;
+    stack: StackInfo;
+    hasGit: boolean;
+    hasClaude: boolean;
+    existingDocs: ExistingDocs;
+}
+export interface StackInfo {
+    language: "typescript" | "javascript" | "python" | "unknown";
+    framework: string | null;
+    packageManager: "npm" | "yarn" | "pnpm" | "bun" | "pip" | "unknown";
+    hasTests: boolean;
+    hasCi: boolean;
+    hasLinter: boolean;
+    hasFormatter: boolean;
+}
+export interface ExistingDocs {
+    hasClaudeMd: boolean;
+    hasAgentsMd: boolean;
+    hasChangelog: boolean;
+    hasReadme: boolean;
+    hasDocsDir: boolean;
+    hasPlansDir: boolean;
+    hasSolutionsDir: boolean;
+}
+/**
+ * Detect project type, stack, and existing infrastructure from the filesystem.
+ */
+export declare function detectProject(root: string): Partial<ProjectInfo>;

package/dist/detect.js

@@ -0,0 +1,127 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Detect project type, stack, and existing infrastructure from the filesystem.
+ */
+export function detectProject(root) {
+    const stack = detectStack(root);
+    const existingDocs = detectExistingDocs(root);
+    const name = detectName(root);
+    return {
+        name,
+        stack,
+        hasGit: existsSync(join(root, ".git")),
+        hasClaude: existsSync(join(root, ".claude")),
+        existingDocs,
+    };
+}
+function detectStack(root) {
+    const info = {
+        language: "unknown",
+        framework: null,
+        packageManager: "unknown",
+        hasTests: false,
+        hasCi: false,
+        hasLinter: false,
+        hasFormatter: false,
+    };
+    // Check for package.json (Node.js/JS/TS projects)
+    const pkgPath = join(root, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            const allDeps = {
+                ...pkg.dependencies,
+                ...pkg.devDependencies,
+            };
+            // Language
+            if (allDeps["typescript"] || existsSync(join(root, "tsconfig.json"))) {
+                info.language = "typescript";
+            }
+            else {
+                info.language = "javascript";
+            }
+            // Framework detection
+            if (allDeps["react"])
+                info.framework = "react";
+            else if (allDeps["next"])
+                info.framework = "nextjs";
+            else if (allDeps["vue"])
+                info.framework = "vue";
+            else if (allDeps["svelte"])
+                info.framework = "svelte";
+            else if (allDeps["express"])
+                info.framework = "express";
+            else if (allDeps["fastify"])
+                info.framework = "fastify";
+            // Package manager
+            if (existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bun.lock")))
+                info.packageManager = "bun";
+            else if (existsSync(join(root, "pnpm-lock.yaml")))
+                info.packageManager = "pnpm";
+            else if (existsSync(join(root, "yarn.lock")))
+                info.packageManager = "yarn";
+            else
+                info.packageManager = "npm";
+            // Tests
+            info.hasTests = !!(allDeps["jest"] ||
+                allDeps["vitest"] ||
+                allDeps["mocha"] ||
+                allDeps["@testing-library/react"] ||
+                pkg.scripts?.test);
+            // Linter
+            info.hasLinter = !!(allDeps["eslint"] ||
+                allDeps["biome"] ||
+                existsSync(join(root, ".eslintrc.json")) ||
+                existsSync(join(root, ".eslintrc.js")) ||
+                existsSync(join(root, "eslint.config.js")) ||
+                existsSync(join(root, "eslint.config.mjs")));
+            // Formatter
+            info.hasFormatter = !!(allDeps["prettier"] ||
+                allDeps["biome"] ||
+                existsSync(join(root, ".prettierrc")) ||
+                existsSync(join(root, ".prettierrc.json")));
+        }
+        catch {
+            // Invalid package.json, continue with defaults
+        }
+    }
+    // Check for Python
+    if (existsSync(join(root, "requirements.txt")) ||
+        existsSync(join(root, "pyproject.toml")) ||
+        existsSync(join(root, "setup.py"))) {
+        info.language = "python";
+        info.packageManager = "pip";
+    }
+    // CI detection
+    info.hasCi =
+        existsSync(join(root, ".github", "workflows")) ||
+            existsSync(join(root, ".gitlab-ci.yml")) ||
+            existsSync(join(root, ".circleci"));
+    return info;
+}
+function detectExistingDocs(root) {
+    return {
+        hasClaudeMd: existsSync(join(root, "CLAUDE.md")),
+        hasAgentsMd: existsSync(join(root, "AGENTS.md")),
+        hasChangelog: existsSync(join(root, "CHANGELOG.md")),
+        hasReadme: existsSync(join(root, "README.md")) ||
+            existsSync(join(root, "readme.md")),
+        hasDocsDir: existsSync(join(root, "docs")),
+        hasPlansDir: existsSync(join(root, "docs", "plans")),
+        hasSolutionsDir: existsSync(join(root, "docs", "solutions")),
+    };
+}
+function detectName(root) {
+    const pkgPath = join(root, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            return pkg.name;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}

package/dist/doctor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `soloship doctor` — audit the user's Claude Code environment against
+ * Soloship's dependency manifest.
+ *
+ * Reads the local filesystem only — no network calls. Reports what's present,
+ * what's missing, and how to install the missing pieces. Exits 0 if all
+ * REQUIRED dependencies are present (recommended ones are informational),
+ * exits 1 if any required dep is missing.
+ */
+export declare function runDoctor(): Promise<void>;

package/dist/doctor.js

@@ -0,0 +1,205 @@
+/**
+ * `soloship doctor` — audit the user's Claude Code environment against
+ * Soloship's dependency manifest.
+ *
+ * Reads the local filesystem only — no network calls. Reports what's present,
+ * what's missing, and how to install the missing pieces. Exits 0 if all
+ * REQUIRED dependencies are present (recommended ones are informational),
+ * exits 1 if any required dep is missing.
+ */
+import chalk from "chalk";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { SOLOSHIP_MANIFEST, } from "./manifest.js";
+export async function runDoctor() {
+    const home = homedir();
+    const settingsPath = join(home, ".claude", "settings.json");
+    const claudeJsonPath = join(home, ".claude.json");
+    const skillsDir = join(home, ".claude", "skills");
+    const settings = readJsonSafe(settingsPath);
+    const claudeJson = readJsonSafe(claudeJsonPath);
+    console.log(chalk.dim("Checking your Claude Code environment..."));
+    console.log("");
+    const sections = [
+        {
+            title: "Plugins",
+            results: SOLOSHIP_MANIFEST.plugins.map((dep) => checkPlugin(dep, settings)),
+        },
+        {
+            title: "MCP servers",
+            results: SOLOSHIP_MANIFEST.mcpServers.map((dep) => checkMcpServer(dep, claudeJson)),
+        },
+        {
+            title: "Global skills",
+            results: SOLOSHIP_MANIFEST.skills.map((dep) => checkSkill(dep, skillsDir)),
+        },
+        {
+            title: "Hooks",
+            results: SOLOSHIP_MANIFEST.hooks.map((dep) => checkHook(dep, settings)),
+        },
+    ];
+    for (const section of sections) {
+        printSection(section);
+    }
+    const exitCode = printSummary(sections);
+    process.exit(exitCode);
+}
+// ---------------------------------------------------------------------------
+// Individual check functions
+// ---------------------------------------------------------------------------
+function checkPlugin(dep, settings) {
+    const enabled = settings?.enabledPlugins || {};
+    // Plugin keys in settings.json look like "superpowers@superpowers-marketplace"
+    const expectedKey = `${dep.id}@${dep.source}`;
+    // Also accept a bare id match for marketplaces whose names we may not know
+    // precisely — any key starting with "dep.id@" counts as present.
+    const present = Object.keys(enabled).some((key) => key === expectedKey || key.startsWith(`${dep.id}@`));
+    return {
+        name: dep.id,
+        present,
+        severity: dep.severity,
+        purpose: dep.purpose,
+        install: dep.install,
+        usedBy: dep.usedBy,
+    };
+}
+function checkMcpServer(dep, claudeJson) {
+    const servers = claudeJson?.mcpServers || {};
+    const present = Object.prototype.hasOwnProperty.call(servers, dep.name);
+    return {
+        name: dep.name,
+        present,
+        severity: dep.severity,
+        purpose: dep.purpose,
+        install: dep.install,
+        notes: dep.notes,
+    };
+}
+function checkSkill(dep, skillsDir) {
+    let present = false;
+    if (existsSync(skillsDir)) {
+        try {
+            const entries = readdirSync(skillsDir);
+            present = entries.includes(dep.name);
+        }
+        catch {
+            // Permission error or similar — treat as missing
+        }
+    }
+    return {
+        name: dep.name,
+        present,
+        severity: dep.severity,
+        purpose: dep.purpose,
+        install: dep.install,
+    };
+}
+function checkHook(dep, settings) {
+    const hooks = settings?.hooks || {};
+    const eventEntries = hooks[dep.event] || [];
+    const present = eventEntries.some((entry) => {
+        const matcher = entry.matcher;
+        if (dep.matcher !== null && matcher !== dep.matcher) {
+            return false;
+        }
+        const nestedHooks = entry.hooks || [];
+        return nestedHooks.some((h) => {
+            const command = h.command;
+            return typeof command === "string" && command.includes(dep.commandContains);
+        });
+    });
+    const matcherLabel = dep.matcher ? `(${dep.matcher})` : "";
+    return {
+        name: `${dep.event}${matcherLabel}`,
+        present,
+        severity: dep.severity,
+        purpose: dep.purpose,
+        install: dep.install,
+    };
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+function printSection(section) {
+    const present = section.results.filter((r) => r.present).length;
+    const total = section.results.length;
+    const required = section.results.filter((r) => r.severity === "required").length;
+    const requiredPresent = section.results.filter((r) => r.severity === "required" && r.present).length;
+    const header = chalk.bold(section.title.toUpperCase()) +
+        chalk.dim(`  (${present}/${total} present` +
+            (required > 0 ? `, ${requiredPresent}/${required} required` : "") +
+            ")");
+    console.log(header);
+    for (const result of section.results) {
+        printResult(result);
+    }
+    console.log("");
+}
+function printResult(result) {
+    const marker = result.present
+        ? chalk.green("  ✓")
+        : result.severity === "required"
+            ? chalk.red("  ✗")
+            : chalk.yellow("  ✗");
+    const nameColumn = result.name.padEnd(28);
+    const severityTag = result.severity === "required" ? chalk.red("[required]") : chalk.dim("[recommended]");
+    console.log(`${marker} ${nameColumn} ${severityTag}`);
+    console.log(`     ${chalk.dim(result.purpose)}`);
+    if (!result.present) {
+        console.log(`     ${chalk.cyan("install:")} ${result.install}`);
+        if (result.notes) {
+            console.log(`     ${chalk.cyan("notes:")}   ${result.notes}`);
+        }
+        if (result.usedBy && result.usedBy.length > 0) {
+            console.log(`     ${chalk.cyan("used by:")} ${result.usedBy.join(", ")}`);
+        }
+    }
+}
+function printSummary(sections) {
+    const all = sections.flatMap((s) => s.results);
+    const requiredMissing = all.filter((r) => r.severity === "required" && !r.present);
+    const recommendedMissing = all.filter((r) => r.severity === "recommended" && !r.present);
+    console.log(chalk.bold("SUMMARY"));
+    if (requiredMissing.length === 0 && recommendedMissing.length === 0) {
+        console.log(chalk.green("  All dependencies present — environment is Soloship-ready."));
+        console.log("");
+        return 0;
+    }
+    if (requiredMissing.length > 0) {
+        console.log(chalk.red(`  ${requiredMissing.length} required dependency missing:`));
+        for (const r of requiredMissing) {
+            console.log(`    - ${r.name}`);
+        }
+    }
+    if (recommendedMissing.length > 0) {
+        console.log(chalk.yellow(`  ${recommendedMissing.length} recommended dependency missing:`));
+        for (const r of recommendedMissing) {
+            console.log(`    - ${r.name}`);
+        }
+    }
+    console.log("");
+    if (requiredMissing.length > 0) {
+        console.log(chalk.red("Some Soloship skills will not work until the required dependencies are installed."));
+        console.log("");
+        return 1;
+    }
+    console.log(chalk.dim("Recommended dependencies improve non-coder workflow but are not strictly required."));
+    console.log("");
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function readJsonSafe(path) {
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(path, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/hooks.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectInfo } from "./detect.js";
+export declare function installHooks(root: string, project: ProjectInfo): Promise<string[]>;