skillshop 2.0.0 → 2.1.0

package/skills-content/shadow-clone/extract-signatures.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+/**
+ * extract-signatures.mjs — Extracts exported symbols and structural signatures
+ * from source files to help shadow-clone understand the public API surface
+ * without reading every line.
+ *
+ * Supports: JavaScript/TypeScript, Python, Go, Rust, Ruby (basic heuristics).
+ *
+ * Usage:
+ *   node extract-signatures.mjs <file-or-directory> [--ext .ts,.tsx,.js]
+ *
+ * Outputs Markdown to stdout with extracted signatures grouped by file.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+
+const args = process.argv.slice(2);
+
+function flag(name) {
+  const i = args.indexOf(name);
+  if (i === -1) return undefined;
+  return args.splice(i, 2)[1];
+}
+
+const extFilter = flag("--ext")?.split(",") ?? null;
+const target = path.resolve(args[0] || ".");
+
+// ---------------------------------------------------------------------------
+// File collection
+// ---------------------------------------------------------------------------
+
+function collectFiles(dir) {
+  try {
+    const out = execSync("git ls-files --cached --others --exclude-standard", {
+      cwd: dir, encoding: "utf-8", maxBuffer: 50 * 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return out.split("\n").map(l => l.trim()).filter(Boolean).map(f => path.join(dir, f));
+  } catch {
+    return walkDir(dir);
+  }
+}
+
+function walkDir(dir) {
+  const skip = new Set(["node_modules", "vendor", "__pycache__", "target", "dist", "build", ".git"]);
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".") && entry.name !== ".") continue;
+    if (skip.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) results.push(...walkDir(full));
+    else results.push(full);
+  }
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Signature extractors
+// ---------------------------------------------------------------------------
+
+const extractors = {
+  // JS / TS
+  ".js": extractJS, ".jsx": extractJS, ".ts": extractJS, ".tsx": extractJS, ".mjs": extractJS,
+  // Python
+  ".py": extractPython,
+  // Go
+  ".go": extractGo,
+  // Rust
+  ".rs": extractRust,
+  // Ruby
+  ".rb": extractRuby,
+};
+
+function extractJS(content) {
+  const sigs = [];
+  const patterns = [
+    // export function / export default function
+    /^export\s+(default\s+)?(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/gm,
+    // export const/let/var
+    /^export\s+(?:const|let|var)\s+(\w+)\s*(?::\s*([^=]+?))?\s*=/gm,
+    // export class / export default class
+    /^export\s+(default\s+)?class\s+(\w+)/gm,
+    // export interface / export type (TS)
+    /^export\s+(?:interface|type)\s+(\w+)/gm,
+    // module.exports
+    /^module\.exports\s*=\s*(\{[\s\S]*?\}|[\w.]+)/gm,
+    // Named exports block: export { ... }
+    /^export\s+\{([^}]+)\}/gm,
+  ];
+  for (const p of patterns) {
+    for (const m of content.matchAll(p)) {
+      sigs.push(m[0].trim().slice(0, 200));
+    }
+  }
+  // React components: const X = (props) => / function X(
+  for (const m of content.matchAll(/^(?:export\s+)?(?:const|function)\s+([A-Z]\w+)\s*(?:=\s*(?:\([^)]*\)|[^=])\s*=>|[\s(])/gm)) {
+    const line = m[0].trim().slice(0, 200);
+    if (!sigs.includes(line)) sigs.push(line);
+  }
+  return sigs;
+}
+
+function extractPython(content) {
+  const sigs = [];
+  for (const m of content.matchAll(/^(?:class|def|async\s+def)\s+\w+[^:]*:/gm)) {
+    sigs.push(m[0].trim().slice(0, 200));
+  }
+  // Top-level assignments that look like exports
+  for (const m of content.matchAll(/^[A-Z_][A-Z_0-9]*\s*=\s*.+/gm)) {
+    sigs.push(m[0].trim().slice(0, 200));
+  }
+  return sigs;
+}
+
+function extractGo(content) {
+  const sigs = [];
+  // Exported functions/methods (start with uppercase)
+  for (const m of content.matchAll(/^func\s+(?:\([^)]+\)\s+)?([A-Z]\w*)\s*\([^)]*\)[^{]*/gm)) {
+    sigs.push(m[0].trim().slice(0, 200));
+  }
+  // Exported types
+  for (const m of content.matchAll(/^type\s+([A-Z]\w*)\s+(?:struct|interface)\s*\{/gm)) {
+    sigs.push(m[0].trim().slice(0, 200));
+  }
+  return sigs;
+}
+
+function extractRust(content) {
+  const sigs = [];
+  for (const m of content.matchAll(/^pub\s+(?:async\s+)?(?:fn|struct|enum|trait|type|const|static|mod)\s+\w+[^{;]*/gm)) {
+    sigs.push(m[0].trim().slice(0, 200));
+  }
+  return sigs;
+}
+
+function extractRuby(content) {
+  const sigs = [];
+  for (const m of content.matchAll(/^\s*(?:class|module|def)\s+\S+/gm)) {
+    sigs.push(m[0].trim().slice(0, 200));
+  }
+  return sigs;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const stat = fs.statSync(target);
+let files;
+if (stat.isDirectory()) {
+  files = collectFiles(target);
+} else {
+  files = [target];
+}
+
+// Filter by extension
+if (extFilter) {
+  files = files.filter(f => extFilter.includes(path.extname(f)));
+} else {
+  files = files.filter(f => extractors[path.extname(f)]);
+}
+
+// Sort for deterministic output
+files.sort();
+
+const output = [];
+output.push("# Extracted Signatures");
+output.push("");
+
+let totalSigs = 0;
+
+for (const file of files) {
+  const ext = path.extname(file);
+  const extractor = extractors[ext];
+  if (!extractor) continue;
+
+  try {
+    const stat = fs.statSync(file);
+    if (stat.size > 512_000) continue; // skip large files
+
+    const content = fs.readFileSync(file, "utf-8");
+    const sigs = extractor(content);
+    if (sigs.length === 0) continue;
+
+    totalSigs += sigs.length;
+    const rel = path.relative(target, file) || path.basename(file);
+    output.push(`## \`${rel}\``);
+    output.push("");
+    for (const sig of sigs) {
+      output.push(`- \`${sig}\``);
+    }
+    output.push("");
+  } catch { /* skip unreadable files */ }
+}
+
+output.push(`---`);
+output.push(`**Total:** ${totalSigs} signatures across ${files.length} files`);
+
+console.log(output.join("\n"));

package/skills-content/shadow-clone/scan-repo.mjs

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+
+/**
+ * scan-repo.mjs — Deterministic repository scanner for the shadow-clone skill.
+ *
+ * Produces a structured Markdown report of a local repository including:
+ *   - File tree (respecting .gitignore via `git ls-files`)
+ *   - Per-extension statistics (file count, lines of code)
+ *   - Key/manifest files detected
+ *   - Dependency summaries extracted from manifest files
+ *   - Entry-point candidates
+ *
+ * Usage:
+ *   node scan-repo.mjs <directory> [--focus <glob>] [--max-depth <n>] [--json]
+ *
+ * Outputs Markdown to stdout (or JSON with --json).
+ */
+
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+// ---------------------------------------------------------------------------
+// CLI args
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+function flag(name) {
+  const i = args.indexOf(name);
+  if (i === -1) return undefined;
+  return args.splice(i, 2)[1];
+}
+function bool(name) {
+  const i = args.indexOf(name);
+  if (i === -1) return false;
+  args.splice(i, 1);
+  return true;
+}
+
+const jsonOutput = bool("--json");
+const focusGlob = flag("--focus");
+const maxDepth = Number(flag("--max-depth")) || Infinity;
+const targetDir = path.resolve(args[0] || ".");
+
+if (!fs.existsSync(targetDir)) {
+  console.error(`Error: directory does not exist: ${targetDir}`);
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// File listing — prefer git ls-files, fallback to recursive readdir
+// ---------------------------------------------------------------------------
+
+function listFilesGit(dir) {
+  try {
+    const out = execSync("git ls-files --cached --others --exclude-standard", {
+      cwd: dir,
+      encoding: "utf-8",
+      maxBuffer: 50 * 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return out
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+function listFilesFallback(dir, prefix = "") {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "vendor" || entry.name === "__pycache__" || entry.name === "target" || entry.name === "dist" || entry.name === "build") continue;
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      results.push(...listFilesFallback(path.join(dir, entry.name), rel));
+    } else {
+      results.push(rel);
+    }
+  }
+  return results;
+}
+
+let allFiles = listFilesGit(targetDir) ?? listFilesFallback(targetDir);
+
+// Apply focus filter
+if (focusGlob) {
+  const pattern = new RegExp(
+    "^" +
+      focusGlob
+        .replace(/\./g, "\\.")
+        .replace(/\*\*/g, "⚡")
+        .replace(/\*/g, "[^/]*")
+        .replace(/⚡/g, ".*") +
+      "$"
+  );
+  allFiles = allFiles.filter((f) => pattern.test(f));
+}
+
+// Apply max-depth filter
+if (maxDepth < Infinity) {
+  allFiles = allFiles.filter((f) => f.split("/").length <= maxDepth);
+}
+
+// ---------------------------------------------------------------------------
+// Analysis
+// ---------------------------------------------------------------------------
+
+const MANIFEST_FILES = new Set([
+  "package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml",
+  "Cargo.toml", "Cargo.lock",
+  "go.mod", "go.sum",
+  "requirements.txt", "setup.py", "setup.cfg", "pyproject.toml", "Pipfile",
+  "Gemfile", "Gemfile.lock",
+  "composer.json",
+  "build.gradle", "build.gradle.kts", "pom.xml",
+  "Makefile", "CMakeLists.txt",
+  "Dockerfile", "docker-compose.yml", "docker-compose.yaml",
+  ".env.example",
+  "tsconfig.json", "jsconfig.json",
+  "vite.config.js", "vite.config.ts", "webpack.config.js", "rollup.config.js",
+  "next.config.js", "next.config.mjs", "nuxt.config.ts",
+  "tailwind.config.js", "tailwind.config.ts", "postcss.config.js",
+  ".eslintrc.js", ".eslintrc.json", "eslint.config.js",
+  ".prettierrc", ".prettierrc.json",
+]);
+
+const ENTRY_PATTERNS = [
+  /^src\/(main|index|app|entry)\.\w+$/,
+  /^(main|index|app)\.\w+$/,
+  /^cmd\/[^/]+\/main\.go$/,
+  /^lib\.rs$/,
+  /^src\/lib\.rs$/,
+  /^src\/main\.rs$/,
+];
+
+const extStats = {};   // ext -> { count, lines }
+const manifests = [];  // relative paths
+const entryPoints = [];
+const dirSet = new Set();
+
+for (const rel of allFiles) {
+  const ext = path.extname(rel) || "(none)";
+  if (!extStats[ext]) extStats[ext] = { count: 0, lines: 0 };
+  extStats[ext].count++;
+
+  // Count lines for source-like files (skip binaries / large blobs)
+  const abs = path.join(targetDir, rel);
+  try {
+    const stat = fs.statSync(abs);
+    if (stat.size < 512_000) {
+      const content = fs.readFileSync(abs, "utf-8");
+      extStats[ext].lines += content.split("\n").length;
+    }
+  } catch { /* skip unreadable */ }
+
+  // Track directories
+  const parts = rel.split("/");
+  for (let i = 1; i < parts.length; i++) {
+    dirSet.add(parts.slice(0, i).join("/"));
+  }
+
+  // Manifests
+  const basename = path.basename(rel);
+  if (MANIFEST_FILES.has(basename) || basename === "README.md" || basename === "README.rst") {
+    manifests.push(rel);
+  }
+
+  // Entry points
+  if (ENTRY_PATTERNS.some((p) => p.test(rel))) {
+    entryPoints.push(rel);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Dependency extraction from key manifests
+// ---------------------------------------------------------------------------
+
+function extractDeps(relPath) {
+  const abs = path.join(targetDir, relPath);
+  const basename = path.basename(relPath);
+  try {
+    const raw = fs.readFileSync(abs, "utf-8");
+    if (basename === "package.json") {
+      const pkg = JSON.parse(raw);
+      return {
+        type: "npm",
+        name: pkg.name,
+        deps: Object.keys(pkg.dependencies || {}),
+        devDeps: Object.keys(pkg.devDependencies || {}),
+        scripts: Object.keys(pkg.scripts || {}),
+      };
+    }
+    if (basename === "go.mod") {
+      const modLine = raw.match(/^module\s+(.+)$/m);
+      const requires = [...raw.matchAll(/^\t(.+?)\s/gm)].map((m) => m[1]);
+      return { type: "go", module: modLine?.[1], deps: requires };
+    }
+    if (basename === "requirements.txt") {
+      const deps = raw.split("\n").map((l) => l.trim().split(/[>=<!\s]/)[0]).filter(Boolean);
+      return { type: "python-requirements", deps };
+    }
+    if (basename === "pyproject.toml") {
+      const nameLine = raw.match(/^name\s*=\s*"(.+?)"/m);
+      return { type: "python-pyproject", name: nameLine?.[1], raw_snippet: raw.slice(0, 500) };
+    }
+    if (basename === "Cargo.toml") {
+      const nameLine = raw.match(/^name\s*=\s*"(.+?)"/m);
+      const depsSection = raw.match(/\[dependencies\]([\s\S]*?)(\[|$)/);
+      const deps = depsSection
+        ? [...depsSection[1].matchAll(/^(\w[\w-]*)/gm)].map((m) => m[1])
+        : [];
+      return { type: "cargo", name: nameLine?.[1], deps };
+    }
+    if (basename === "Gemfile") {
+      const gems = [...raw.matchAll(/gem\s+['"](.+?)['"]/g)].map((m) => m[1]);
+      return { type: "ruby", deps: gems };
+    }
+  } catch { /* skip */ }
+  return null;
+}
+
+const depSummaries = {};
+for (const m of manifests) {
+  const info = extractDeps(m);
+  if (info) depSummaries[m] = info;
+}
+
+// ---------------------------------------------------------------------------
+// Build file tree (compact)
+// ---------------------------------------------------------------------------
+
+function buildTree(files, maxItems = 500) {
+  const truncated = files.length > maxItems;
+  const subset = truncated ? files.slice(0, maxItems) : files;
+  const lines = [];
+  const dirs = new Map(); // dir -> files[]
+
+  for (const f of subset) {
+    const dir = path.dirname(f);
+    if (!dirs.has(dir)) dirs.set(dir, []);
+    dirs.get(dir).push(path.basename(f));
+  }
+
+  const sortedDirs = [...dirs.keys()].sort();
+  for (const dir of sortedDirs) {
+    if (dir !== ".") lines.push(`${dir}/`);
+    for (const file of dirs.get(dir).sort()) {
+      lines.push(dir === "." ? `  ${file}` : `  ${dir}/${file}`);
+    }
+  }
+
+  if (truncated) lines.push(`  ... and ${files.length - maxItems} more files`);
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Output
+// ---------------------------------------------------------------------------
+
+const report = {
+  target: targetDir,
+  totalFiles: allFiles.length,
+  totalDirs: dirSet.size,
+  extensions: Object.entries(extStats)
+    .sort((a, b) => b[1].count - a[1].count)
+    .map(([ext, s]) => ({ ext, ...s })),
+  manifests,
+  entryPoints,
+  depSummaries,
+  tree: buildTree(allFiles),
+};
+
+if (jsonOutput) {
+  console.log(JSON.stringify(report, null, 2));
+} else {
+  const lines = [];
+  lines.push(`# Repository Scan: ${path.basename(targetDir)}`);
+  lines.push("");
+  lines.push(`**Path:** \`${targetDir}\``);
+  lines.push(`**Files:** ${report.totalFiles} | **Directories:** ${report.totalDirs}`);
+  lines.push("");
+
+  // Extension stats
+  lines.push("## File Statistics");
+  lines.push("");
+  lines.push("| Extension | Files | Lines |");
+  lines.push("|-----------|------:|------:|");
+  for (const { ext, count, lines: loc } of report.extensions) {
+    lines.push(`| ${ext} | ${count} | ${loc.toLocaleString()} |`);
+  }
+  lines.push("");
+
+  // Key files
+  lines.push("## Key / Manifest Files");
+  lines.push("");
+  for (const m of manifests) lines.push(`- \`${m}\``);
+  lines.push("");
+
+  // Entry points
+  if (entryPoints.length) {
+    lines.push("## Detected Entry Points");
+    lines.push("");
+    for (const e of entryPoints) lines.push(`- \`${e}\``);
+    lines.push("");
+  }
+
+  // Dependencies
+  if (Object.keys(depSummaries).length) {
+    lines.push("## Dependency Summary");
+    lines.push("");
+    for (const [file, info] of Object.entries(depSummaries)) {
+      lines.push(`### \`${file}\` (${info.type})`);
+      if (info.name) lines.push(`**Name:** ${info.name}`);
+      if (info.module) lines.push(`**Module:** ${info.module}`);
+      if (info.deps?.length) {
+        lines.push(`**Dependencies (${info.deps.length}):** ${info.deps.join(", ")}`);
+      }
+      if (info.devDeps?.length) {
+        lines.push(`**Dev Dependencies (${info.devDeps.length}):** ${info.devDeps.join(", ")}`);
+      }
+      if (info.scripts?.length) {
+        lines.push(`**Scripts:** ${info.scripts.join(", ")}`);
+      }
+      if (info.raw_snippet) {
+        lines.push("```toml");
+        lines.push(info.raw_snippet);
+        lines.push("```");
+      }
+      lines.push("");
+    }
+  }
+
+  // File tree
+  lines.push("## File Tree");
+  lines.push("");
+  lines.push("```");
+  lines.push(report.tree);
+  lines.push("```");
+
+  console.log(lines.join("\n"));
+}

package/skills-content/ship/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: ship
+description: Runs a repository-aware workflow to isolate, plan, implement, review, validate, and push a change.
+metadata:
+  author: Daniel Fosco
+  version: "2026.8.30"
+---
+
+# Ship Skill
+
+> Triggered by: "ship", "ship this", "ship a feature", "ship it", "ship a change"
+>
+> This skill ships a change to a reviewable remote branch. It must not publish a package or create a release unless the user separately invokes the release workflow.
+
+## What This Does
+
+Carries a change from repository discovery through implementation, validation, review, documentation, and push. It follows the target repository's branch, worktree, planning, testing, commit, and review conventions rather than prescribing a particular toolchain.
+
+## Step 1: Discover Repository Policy
+
+Before choosing a branch or path, inspect repository instructions, current worktrees, branch state, remotes, package or build tooling, required checks, contribution guidance, and available local skills. Identify whether the repository requires:
+
+- a worktree or permits work on the current branch;
+- a branch naming convention or issue identifier;
+- a checked-in plan or change request;
+- specific test, lint, build, formatting, or documentation commands;
+- commit-message conventions or attribution trailers;
+- a pull request instead of a direct branch push.
+
+Do not turn examples from this skill into repository policy.
+
+## Step 2: Isolate The Change
+
+Use the `worktree` skill when available and appropriate. Derive a short branch name from the requested outcome, preserving any user-provided branch name and documented prefix. Confirm the name only when it is ambiguous or repository policy requires confirmation.
+
+Use the path returned by the worktree workflow for all subsequent commands. Do not assume it is `worktrees/<branch-name>`. Never discard changes in the source or target worktree.
+
+If the repository explicitly does not use worktrees, create or use the required branch without silently switching a dirty working tree.
+
+## Step 3: Plan Against Goals
+
+Explore the relevant code before writing a plan. Define one to three measurable user-facing goals, then describe the smallest approach that satisfies them, affected files, implementation steps, edge cases, compatibility concerns, and validation.
+
+Write the plan only when the repository has an established plan location or the user asks for a plan artifact. Otherwise keep it in task tracking. If approval is needed because the request is ambiguous, risky, destructive, or materially larger than stated, present the tradeoff and ask before implementation; do not add an unconditional approval gate to routine work.
+
+Use repository-local issue or task tooling when available and useful. Do not require a specific tracker.
+
+## Step 4: Implement
+
+Make the smallest correct changes consistent with existing architecture and style. Preserve unrelated worktree changes. Add or update tests alongside the behavior they cover using the repository's existing framework and patterns.
+
+Do not split implementation and tests into separate commits by default. Commit boundaries should represent coherent reviewable changes, not phases imposed by this skill.
+
+## Step 5: Validate
+
+Run the checks discovered in Step 1. Prefer documented aggregate commands. If no aggregate command exists, run the relevant tests and static checks for the changed area, expanding to the full suite when risk or repository policy warrants it.
+
+Do not assume Node.js, npm, Vitest, or scripts named `lint`, `build`, `test`, or `dev`. Report any check that could not run and why.
+
+## Step 6: Review
+
+Review the full branch diff against its base, not only the last commit. Check for behavioral regressions, security problems, broken interfaces, concurrency or error-path failures, missing tests, and needless complexity.
+
+Use an available review agent or skill when it adds value, but do not require an agent name that may not exist. Apply high-confidence fixes, rerun affected checks, and avoid speculative refactors that do not serve a stated goal.
+
+Read existing architecture documentation for changed files when present. Update generated or authored architecture docs only through the repository's documented process.
+
+## Step 7: Document And Commit
+
+Update user-facing or architectural documentation when behavior, interfaces, operations, or durable design contracts changed. Do not edit every common documentation filename mechanically.
+
+Stage only intended files and inspect the staged diff. Follow the repository's commit conventions. Add co-author or sign-off trailers only when required by repository policy or requested by the user; never hardcode an identity.
+
+## Step 8: Push And Report
+
+Push the branch to the configured remote only when shipping includes a push under the user's request and repository policy. Use the actual remote name rather than assuming `origin`. If the repository expects a pull request and the user asked for one, create it using the repository template and return its URL.
+
+Report:
+
+- branch and worktree path;
+- concise change summary;
+- validation commands and results;
+- review findings resolved or left open;
+- commit, remote branch, and pull request URL when created;
+- any manual verification still required.
+
+Start a development server only when requested or needed for verification. Use the documented command and report how to stop it.
+
+## Rules
+
+- Never ship directly to a protected or default branch unless repository policy and the user explicitly require it.
+- Never release or publish as part of this workflow.
+- Never assume a worktree directory, branch prefix, package manager, test framework, tracker, plan path, dev command, remote name, or commit trailer.
+- Stop before destructive operations or unresolved high-severity failures; ordinary recoverable failures should be investigated and fixed.
+- Preserve unrelated changes and state exactly what was pushed.