soloship 0.1.0

package/dist/manifest.js

@@ -0,0 +1,90 @@
+/**
+ * Soloship dependency manifest.
+ *
+ * Declares the companion plugins, MCP servers, user-scope skills, and global
+ * hooks that Soloship either REQUIRES (its skills will break without them) or
+ * RECOMMENDS (non-coder workflow is materially improved by having them).
+ *
+ * The `doctor` command audits this list against the user's actual
+ * `~/.claude/` environment and reports what's missing with install commands.
+ *
+ * Edit this file when Soloship adds or drops companion dependencies. The
+ * manifest is the single source of truth for dependency information — do not
+ * hard-code checks elsewhere.
+ */
+export const SOLOSHIP_MANIFEST = {
+    plugins: [
+        {
+            id: "superpowers",
+            source: "superpowers-marketplace",
+            severity: "required",
+            purpose: "Brainstorming, plan-writing, debugging, and parallel-agent primitives.",
+            usedBy: [
+                "soloship-brainstorm",
+                "soloship-plan",
+                "soloship-debug",
+                "soloship-implement",
+            ],
+            install: "Install 'superpowers' from the Claude Code plugin marketplace. Soloship routers will silently fail without it.",
+        },
+        {
+            id: "compound-engineering",
+            source: "every-marketplace",
+            severity: "required",
+            purpose: "Solution doc authoring, agent-native workflows, review orchestration.",
+            usedBy: ["soloship-learn", "soloship-review"],
+            install: "Install 'compound-engineering' from the Every marketplace in Claude Code.",
+        },
+    ],
+    mcpServers: [
+        {
+            name: "obsidian",
+            severity: "recommended",
+            purpose: "Cross-project read/search access to an Obsidian vault.",
+            install: 'claude mcp add -s user obsidian -- npx -y obsidian-mcp "<VAULT_PATH>"',
+            notes: "Replace <VAULT_PATH> with the absolute path to your vault (e.g., '/Users/you/Documents/vault').",
+        },
+        {
+            name: "context7",
+            severity: "recommended",
+            purpose: "Up-to-date documentation for 9,000+ libraries injected into prompts.",
+            install: "claude mcp add -s user context7 -- npx -y @upstash/context7-mcp",
+        },
+        {
+            name: "chrome-devtools",
+            severity: "recommended",
+            purpose: "Headless browser automation for QA and testing flows.",
+            install: "claude mcp add -s user chrome-devtools -- npx -y chrome-devtools-mcp@latest",
+        },
+    ],
+    skills: [
+        {
+            name: "gstack",
+            severity: "recommended",
+            purpose: "Command bundle that provides office-hours, plan reviews (eng/CEO/design), QA, CSO, design-review, retro, and others. Soloship skills delegate to gstack for review and QA workflows.",
+            install: "gstack has its own install path — check its README. It typically deploys as a directory under ~/.claude/skills/gstack plus individual symlinked skills (office-hours, plan-eng-review, qa, cso, etc.).",
+        },
+        {
+            name: "log",
+            severity: "recommended",
+            purpose: "Session capture with decisions, rationale, and alternatives.",
+            install: "The Soloship log skill is shipped as part of Soloship. If missing, re-run `soloship init` from a project directory.",
+        },
+        {
+            name: "obsidian-second-brain",
+            severity: "recommended",
+            purpose: "Vault-aware thinking commands (/challenge, /emerge, /connect) plus ~20 content-ingestion and synthesis commands.",
+            install: 'git clone https://github.com/eugeniughelbur/obsidian-second-brain ~/.claude/skills/obsidian-second-brain && bash ~/.claude/skills/obsidian-second-brain/scripts/setup.sh "<VAULT_PATH>"',
+        },
+    ],
+    hooks: [
+        {
+            event: "SessionStart",
+            matcher: "compact",
+            commandContains: "reinject-claude-md-after-compact",
+            severity: "recommended",
+            purpose: "Re-injects the nearest CLAUDE.md after auto-compaction so the agent doesn't forget project rules mid-session.",
+            install: "Add a SessionStart hook with matcher 'compact' in ~/.claude/settings.json pointing at a script that reads stdin, walks up from `cwd` to find CLAUDE.md, and outputs it as `additionalContext` JSON. See the Soloship docs for a reference script.",
+        },
+    ],
+};

package/dist/pkg.d.ts

@@ -0,0 +1 @@
+export declare function getVersion(): string;

package/dist/pkg.js

@@ -0,0 +1,9 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export function getVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = join(here, "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return pkg.version;
+}

package/dist/rollback.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Rollback to the last Soloship safety snapshot.
+ *
+ * Checkpoints are created automatically at session start by the checkpoint hook.
+ * The checkpoint reference (a commit SHA) is stored in .ai/.last-checkpoint.
+ *
+ * Rollback strategy:
+ * 1. If .ai/.last-checkpoint exists, reset to that commit
+ * 2. All changes after the checkpoint become uncommitted (soft reset)
+ * 3. User can then discard or keep specific changes
+ */
+export declare function runRollback(): Promise<void>;

package/dist/rollback.js

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import chalk from "chalk";
+/**
+ * Rollback to the last Soloship safety snapshot.
+ *
+ * Checkpoints are created automatically at session start by the checkpoint hook.
+ * The checkpoint reference (a commit SHA) is stored in .ai/.last-checkpoint.
+ *
+ * Rollback strategy:
+ * 1. If .ai/.last-checkpoint exists, reset to that commit
+ * 2. All changes after the checkpoint become uncommitted (soft reset)
+ * 3. User can then discard or keep specific changes
+ */
+export async function runRollback() {
+    const root = process.cwd();
+    // Verify git repo
+    try {
+        execSync("git rev-parse --is-inside-work-tree", {
+            cwd: root,
+            stdio: "pipe",
+        });
+    }
+    catch {
+        console.error(chalk.red("Not a git repository. Rollback requires git."));
+        process.exit(1);
+    }
+    const checkpointFile = join(root, ".ai", ".last-checkpoint");
+    if (!existsSync(checkpointFile)) {
+        console.error(chalk.red("No checkpoint found.") +
+            " Checkpoints are created automatically when a Claude Code session starts.");
+        console.error(chalk.dim("If this is a fresh project, run a Claude Code session first to create a checkpoint."));
+        process.exit(1);
+    }
+    const checkpointSha = readFileSync(checkpointFile, "utf-8").trim();
+    if (!checkpointSha) {
+        console.error(chalk.red("Checkpoint file is empty."));
+        process.exit(1);
+    }
+    // Verify the checkpoint commit exists
+    try {
+        execSync(`git cat-file -e ${checkpointSha}`, {
+            cwd: root,
+            stdio: "pipe",
+        });
+    }
+    catch {
+        console.error(chalk.red(`Checkpoint commit ${checkpointSha} not found.`) +
+            " It may have been garbage-collected or the history was rewritten.");
+        process.exit(1);
+    }
+    // Check for pre-session stash snapshot
+    const stashFile = join(root, ".ai", ".last-checkpoint-stash");
+    const stashSha = existsSync(stashFile)
+        ? readFileSync(stashFile, "utf-8").trim()
+        : null;
+    // Show what will be rolled back
+    const shortSha = checkpointSha.substring(0, 7);
+    const currentSha = execSync("git rev-parse --short HEAD", {
+        cwd: root,
+        encoding: "utf-8",
+    }).trim();
+    console.log("");
+    console.log(chalk.bold("Soloship Rollback"));
+    console.log("");
+    console.log(`  Restore point:  ${chalk.cyan(shortSha)} (saved when AI session started)`);
+    console.log(`  You are now at: ${chalk.cyan(currentSha)}`);
+    if (stashSha) {
+        console.log(`  Your pre-session work: ${chalk.cyan("preserved")}`);
+    }
+    console.log("");
+    // Count commits between checkpoint and HEAD
+    try {
+        const commitCount = execSync(`git rev-list --count ${checkpointSha}..HEAD`, { cwd: root, encoding: "utf-8" }).trim();
+        if (commitCount === "0") {
+            // Check for uncommitted changes
+            const hasChanges = execSync("git status --porcelain", {
+                cwd: root,
+                encoding: "utf-8",
+            }).trim().length > 0;
+            if (!hasChanges) {
+                console.log(chalk.green("Already at checkpoint.") + " Nothing to roll back.");
+                return;
+            }
+            console.log(`  Removing changes made during this session...`);
+            // Discard all current changes
+            execSync("git checkout -- .", { cwd: root, stdio: "pipe" });
+            execSync("git clean -fd", { cwd: root, stdio: "pipe" });
+            // Restore pre-session changes if they were captured
+            if (stashSha) {
+                restorePreSessionChanges(root, stashSha);
+            }
+        }
+        else {
+            console.log(`  Undoing ${chalk.yellow(commitCount)} commit(s) from this session...`);
+            // Hard reset to checkpoint — discards agent's commits and working tree changes
+            execSync(`git reset --hard ${checkpointSha}`, {
+                cwd: root,
+                stdio: "pipe",
+            });
+            // Restore pre-session changes if they were captured
+            if (stashSha) {
+                restorePreSessionChanges(root, stashSha);
+            }
+        }
+    }
+    catch (err) {
+        console.error(chalk.red("Rollback failed:"), err);
+        process.exit(1);
+    }
+    console.log("");
+    console.log(chalk.green.bold("Rolled back to checkpoint."));
+    if (stashSha) {
+        console.log(chalk.dim("Your pre-session changes have been restored."));
+    }
+    console.log("");
+}
+function restorePreSessionChanges(root, stashSha) {
+    try {
+        // Verify the stash object still exists (git gc could have collected it)
+        execSync(`git cat-file -e ${stashSha}`, { cwd: root, stdio: "pipe" });
+        execSync(`git stash apply ${stashSha}`, { cwd: root, stdio: "pipe" });
+    }
+    catch {
+        console.log(chalk.yellow("Could not restore pre-session changes (snapshot may have been cleaned up)." +
+            " Working tree is clean at the checkpoint commit."));
+    }
+}

package/dist/rules.d.ts

@@ -0,0 +1 @@
+export declare function installRules(root: string): Promise<string[]>;

package/dist/rules.js

@@ -0,0 +1,119 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export async function installRules(root) {
+    const results = [];
+    const rulesDir = join(root, ".claude", "rules");
+    if (!existsSync(rulesDir)) {
+        mkdirSync(rulesDir, { recursive: true });
+    }
+    const rules = {
+        "solution-search.md": RULE_SOLUTION_SEARCH,
+        "plan-materialization.md": RULE_PLAN_MATERIALIZATION,
+        "plan-rationale.md": RULE_PLAN_RATIONALE,
+        "plan-lifecycle.md": RULE_PLAN_LIFECYCLE,
+    };
+    for (const [filename, content] of Object.entries(rules)) {
+        const path = join(rulesDir, filename);
+        if (!existsSync(path)) {
+            writeFileSync(path, content);
+            results.push(filename);
+        }
+        else {
+            results.push(`${filename} (exists, skipped)`);
+        }
+    }
+    return results;
+}
+const RULE_SOLUTION_SEARCH = `# Solution Search Before Work (Auto-Loaded)
+
+## The Rule
+
+Before planning, debugging, or reviewing any implementation, check if \`docs/solutions/\` exists in the project. If it does, search it for prior art related to the current task.
+
+## When to Search
+
+- Before starting any plan (Think or Plan phase)
+- At the start of any debugging session
+- When reviewing an implementation against a plan
+- When encountering an error message
+
+## How to Search
+
+1. Grep \`docs/solutions/\` for keywords: component names, error messages, file paths, symptoms
+2. Search the entire directory — never limit to a single category
+3. Read frontmatter of matches to assess relevance
+4. Read full doc if relevant, and apply its prevention strategies
+
+## What to Do With Results
+
+- Reference relevant solutions in plans and reviews
+- Apply prevention strategies from past solutions
+- If the current problem matches a documented one, follow the existing solution
+`;
+const RULE_PLAN_MATERIALIZATION = `# Plan Materialization (Auto-Loaded)
+
+## The Rule
+
+**Planning mode is for thinking. The plan file is the deliverable.**
+
+After exiting planning mode, the FIRST action — before offering to clear context or implement — is writing the plan to \`docs/plans/YYYY-MM-DD-<slug>.md\`.
+
+## Sequence
+
+1. Enter planning mode (think, design, iterate with user)
+2. Exit planning mode
+3. IMMEDIATELY write plan to docs/plans/YYYY-MM-DD-<slug>.md
+4. THEN offer to clear context and implement
+
+Never skip step 3. Never say "I'll write the plan after we clear." The plan file must exist before the session boundary.
+
+## Why This Exists
+
+Planning mode disables file writes. This creates a gap where good planning work stays in conversation context but never reaches the filesystem. Context clears destroy it. This rule closes that gap.
+`;
+const RULE_PLAN_RATIONALE = `# Plan Rationale Requirements (Auto-Loaded)
+
+Every implementation plan must carry enough reasoning for a fresh agent with zero context to understand why decisions were made.
+
+## Inline Rationale
+
+Each phase or major step must include a **Why** line explaining the motivation. Not just "delete these files" but "delete these files because they are dead code — no imports reference them."
+
+## Key Decisions Section
+
+Every plan must end with a **Key Decisions** section listing non-obvious choices and their reasoning. A decision qualifies as "key" if:
+- Choosing between two or more reasonable approaches
+- Deleting code or removing functionality
+- Changing defaults or stored state schema
+- Imposing architectural constraints
+- Anything a reviewer might question
+`;
+const RULE_PLAN_LIFECYCLE = `# Plan Lifecycle (Auto-Loaded)
+
+## Location
+
+All plans go in \`docs/plans/\`. Naming: \`YYYY-MM-DD-<slug>.md\`
+
+## Cleanup After Completion
+
+### Small Plans (delete after commit)
+
+ALL of these must be true:
+- Single phase / fewer than 3 tasks
+- Touches fewer than 5 files
+- No architectural decisions worth preserving
+
+**Action:** \`git rm\` the plan file after the final commit.
+
+### Large Plans (archive)
+
+ANY of these is true:
+- Multiple phases or 3+ tasks
+- Touches 5+ files
+- Contains architectural decisions
+- Spans multiple sessions
+
+**Action:** \`git mv\` to \`docs/plans/archive/\`
+
+When in doubt, archive. Deleting knowledge is worse than keeping a small file.
+`;

package/dist/scaffold.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectInfo } from "./detect.js";
+interface ScaffoldResult {
+    path: string;
+    action: "created" | "exists" | "updated";
+}
+export declare function scaffoldDocs(root: string, project: ProjectInfo): Promise<ScaffoldResult[]>;
+export {};

package/dist/scaffold.js

@@ -0,0 +1,138 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { generateClaudeMd, generateAgentsMd, generateSolutionGuide, generateChangelog, } from "./templates.js";
+export async function scaffoldDocs(root, project) {
+    const results = [];
+    // Create directory structure
+    const dirs = [
+        "docs/plans",
+        "docs/plans/archive",
+        "docs/solutions",
+        "docs/architecture",
+        "docs/architecture/decisions",
+        "docs/audit",
+    ];
+    for (const dir of dirs) {
+        const fullPath = join(root, dir);
+        if (!existsSync(fullPath)) {
+            mkdirSync(fullPath, { recursive: true });
+            results.push({ path: dir + "/", action: "created" });
+        }
+        else {
+            results.push({ path: dir + "/", action: "exists" });
+        }
+    }
+    // CLAUDE.md — only create if doesn't exist
+    if (!project.existingDocs.hasClaudeMd) {
+        const content = generateClaudeMd(project);
+        writeFileSync(join(root, "CLAUDE.md"), content);
+        results.push({ path: "CLAUDE.md", action: "created" });
+    }
+    else {
+        results.push({ path: "CLAUDE.md", action: "exists" });
+    }
+    // AGENTS.md — root level, only if doesn't exist
+    if (!project.existingDocs.hasAgentsMd) {
+        const content = generateAgentsMd(project);
+        writeFileSync(join(root, "AGENTS.md"), content);
+        results.push({ path: "AGENTS.md", action: "created" });
+    }
+    else {
+        results.push({ path: "AGENTS.md", action: "exists" });
+    }
+    // CHANGELOG.md — only if doesn't exist
+    if (!project.existingDocs.hasChangelog) {
+        const content = generateChangelog(project);
+        writeFileSync(join(root, "CHANGELOG.md"), content);
+        results.push({ path: "CHANGELOG.md", action: "created" });
+    }
+    else {
+        results.push({ path: "CHANGELOG.md", action: "exists" });
+    }
+    // Solution Guide — always create (it's a reference doc)
+    const solutionGuidePath = join(root, "docs", "SOLUTION_GUIDE.md");
+    if (!existsSync(solutionGuidePath)) {
+        writeFileSync(solutionGuidePath, generateSolutionGuide());
+        results.push({ path: "docs/SOLUTION_GUIDE.md", action: "created" });
+    }
+    else {
+        results.push({ path: "docs/SOLUTION_GUIDE.md", action: "exists" });
+    }
+    // Semgrep config for automated security scanning
+    const semgrepPath = join(root, ".semgrep.yml");
+    if (!existsSync(semgrepPath)) {
+        writeFileSync(semgrepPath, generateSemgrepConfig());
+        results.push({ path: ".semgrep.yml", action: "created" });
+    }
+    else {
+        results.push({ path: ".semgrep.yml", action: "exists" });
+    }
+    return results;
+}
+function generateSemgrepConfig() {
+    return `# Semgrep configuration — Soloship automated security scanning
+# Runs automatically on every commit via Claude Code hook.
+# Critical findings block the commit. Medium findings warn.
+#
+# Install semgrep: pip install semgrep (or pipx install semgrep)
+# Manual scan: semgrep --config .semgrep.yml src/
+
+rules:
+  # --- Injection ---
+  - id: hardcoded-secret
+    pattern-either:
+      - pattern: $KEY = "..."
+      - pattern: $KEY = '...'
+    metavariable-regex:
+      metavariable: $KEY
+      regex: (?i)(api_key|secret|password|token|credential|private_key)
+    message: "Possible hardcoded secret in $KEY. Use environment variables instead."
+    severity: ERROR
+    languages: [javascript, typescript, python, ruby]
+
+  - id: sql-string-concat
+    pattern-either:
+      - pattern: |
+          $QUERY = "..." + $INPUT + "..."
+      - pattern: |
+          $QUERY = \`...\${$INPUT}...\`
+    message: "SQL query built with string concatenation. Use parameterized queries."
+    severity: ERROR
+    languages: [javascript, typescript]
+
+  - id: eval-usage
+    pattern-either:
+      - pattern: eval(...)
+      - pattern: new Function(...)
+    message: "eval() or new Function() detected. This enables code injection."
+    severity: ERROR
+    languages: [javascript, typescript]
+
+  # --- XSS ---
+  - id: innerhtml-usage
+    pattern: $EL.innerHTML = $VALUE
+    message: "innerHTML assignment detected. Use textContent or sanitize input."
+    severity: WARNING
+    languages: [javascript, typescript]
+
+  - id: dangerously-set-html
+    pattern: dangerouslySetInnerHTML={...}
+    message: "dangerouslySetInnerHTML usage. Ensure input is sanitized."
+    severity: WARNING
+    languages: [javascript, typescript]
+
+  # --- Auth ---
+  - id: jwt-none-algorithm
+    pattern-either:
+      - pattern: |
+          jwt.sign($PAYLOAD, ..., {algorithm: "none"})
+      - pattern: |
+          jwt.verify($TOKEN, ..., {algorithms: ["none"]})
+    message: "JWT with 'none' algorithm is insecure."
+    severity: ERROR
+    languages: [javascript, typescript]
+
+  # Extend with p/owasp-top-ten for comprehensive coverage:
+  # semgrep --config p/owasp-top-ten --config .semgrep.yml src/
+`;
+}

package/dist/templates.d.ts

@@ -0,0 +1,5 @@
+import type { ProjectInfo } from "./detect.js";
+export declare function generateClaudeMd(project: ProjectInfo): string;
+export declare function generateAgentsMd(project: ProjectInfo): string;
+export declare function generateChangelog(project: ProjectInfo): string;
+export declare function generateSolutionGuide(): string;