@spunto/build 0.9.0 → 0.10.0

package/README.md

@@ -122,6 +122,15 @@ orchestrates setup phase by phase instead of a container running one long CMD. T
 because they share every helper in the file; splitting them out would fork the helpers, which is
 the duplication this package exists to remove.
 
+**Skills** (0.10.0): `buildSkillsScript({ sources, discoveryDirs })` clones git *skill sources*
+into `~/.spunto/skills/<id>/` and links each retained skill (a directory with a `SKILL.md`) into
+the harness's discovery directories — one symlink per skill, never over an existing entry, and a
+refresh only removes the links it posed itself (a ledger records them). The same script is the
+`skills` setup phase (`skills` param of `buildSetupScript` / `buildSetupPlan`, after `dotfiles`,
+before `clone`) and a refresh a control plane can run later. Which skills are retained is decided
+by the caller (`linkByDefault` + `include` / `exclude`); the script only applies it against what
+the ref actually holds. It never fails the setup: problems are printed with a `[skills]` prefix.
+
 ### `@spunto/build/catalogs` — what a project picker offers
 
 `AVAILABLE_IMAGES`, `AVAILABLE_FEATURES`, `SUGGESTED_EXTENSIONS`. Data, but shared data: the two

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Spunto's shared Build engine — the devcontainer image protocol and VS Code extension registry clients, with no database, no HTTP framework and no UI.",
   "type": "module",
   "license": "MIT",

package/src/script/index.ts

@@ -27,4 +27,9 @@ export {
 } from "./setup-script"
 export type { ResolvedFeature, SetupPhase, SetupScriptParams, StartScriptParams } from "./setup-script"
 
+// Organization skills (RFC 0033): the same script is a setup phase and, before each delegated
+// task, a refresh the control plane runs on its own.
+export { buildSkillsScript, skillFetchUrlEnv, SKILLS_DIR } from "./skills"
+export type { SkillSource, SkillsScriptParams } from "./skills"
+
 export { LOCAL_FEATURE_SCRIPTS, localFeatureScript } from "./local-features"

package/src/script/setup-script.ts

@@ -9,6 +9,7 @@ import {
 import { stepEndLine, stepStartLine, type BuildStep, type BuildStepKind } from "../steps/build-steps"
 import type { SetupStatus } from "../types/index"
 import { localFeatureScript } from "./local-features"
+import { buildSkillsScript, type SkillsScriptParams } from "./skills"
 
 // ─── Internal helpers ──────────────────────────────────────────────────────────
 
@@ -880,6 +881,37 @@ export type SetupScriptParams = {
   // Git branch chosen when this worker was created (workers.branch): checked out for every repo
   // of the project, overriding each repository's own default branch. Null/absent → default branch.
   branch?: string | null
+  /**
+   * Skills the organization makes available in this worker (Spunto Cloud RFC 0033), already
+   * resolved: which sources, which ref, which skills to link. Materialized in their own phase,
+   * after the dotfiles (so a dotfiles install cannot overwrite a link, and a skill of the member's
+   * own wins a name collision) and before the project's clones. Absent → no phase at all.
+   */
+  skills?: SkillsScriptParams
+}
+
+/**
+ * The `skills` phase body: writes the skills script to a temp file and runs it as the user, with
+ * the worker's secrets in its environment (a member may set `CLAUDE_CONFIG_DIR` as one, and the
+ * discovery directory is derived from it). Never fails the setup — see ./skills.ts.
+ */
+function skillsBlock(params: {
+  homeDir: string
+  username: string
+  skills?: SkillsScriptParams
+  userEnvSecrets?: Record<string, string>
+}): string[] {
+  const { homeDir, username, skills, userEnvSecrets } = params
+  if (!skills || skills.sources.length === 0) return []
+  const script = buildSkillsScript({ ...skills, homeDir })
+  if (!script) return []
+  return [
+    ...banner(`SETUP: SKILLS (${skills.sources.length})`),
+    `echo ${JSON.stringify(b64(script))} | base64 -d > /tmp/spunto-skills.sh`,
+    `chmod 644 /tmp/spunto-skills.sh`,
+    `su ${username} -c "cd ${homeDir} && ${envPrefix(userEnvSecrets)}bash /tmp/spunto-skills.sh" 2>&1 || echo "[skills] ✗ skills script exited with $?"`,
+    `rm -f /tmp/spunto-skills.sh`,
+  ]
 }
 
 export function buildSetupScript(params: SetupScriptParams): { script: string } {
@@ -1052,6 +1084,13 @@ export function buildSetupScript(params: SetupScriptParams): { script: string }
     )
   }
 
+  // ── 4b. Organization skills (RFC 0033) ─────────────────────────────────────
+  const skillLines = skillsBlock({ homeDir, username, skills: params.skills, userEnvSecrets })
+  if (skillLines.length > 0) {
+    mpAt(mkStatus(dotfilesRepo ? "dotfiles" : hasCredentials ? "credentials" : "initializing", allReposPending, pc0, null), "skills")
+    push(...skillLines)
+  }
+
   // ── 5. Clone repos ────────────────────────────────────────────────────────
   if (project.repositories.length > 0) {
     push(...banner(`SETUP: CLONE REPOSITORIES (${project.repositories.length})`))
@@ -1432,7 +1471,7 @@ export function buildStartScript(params: StartScriptParams): { script: string; h
 /** One setup phase the agent execs via `docker exec`, wrapped in a native OTel span. */
 export type SetupPhase = {
   /** Timing-key / span-suffix (`setup.<id>`) and the phase's short identity. */
-  id: "credentials" | "shell" | "dotfiles" | "clone" | "postCreate" | "postStart"
+  id: "credentials" | "shell" | "dotfiles" | "skills" | "clone" | "postCreate" | "postStart"
   /** Human label for logs. */
   label: string
   /** Self-contained bash (runs as root via `docker exec`; `su vscode` inside where needed). */
@@ -1976,6 +2015,17 @@ export function buildSetupPlan(params: SetupScriptParams): {
     phases.push({ id: "dotfiles", label: "Dotfiles", script: l.join("\n"), runsOnRestart: false, statusStart: st, statusEnd: st })
   }
 
+  // ── skills (RFC 0033) ──────────────────────────────────────────────────────
+  // Re-run on every start: the script fast-forwards the clones through the credential helper
+  // (the URL minted for the first boot has expired by then) and re-links, and it is idempotent.
+  {
+    const l = skillsBlock({ homeDir, username, skills: params.skills, userEnvSecrets })
+    if (l.length > 0) {
+      const st = status(dotfilesRepo ? "dotfiles" : hasCredentials ? "credentials" : "initializing", allReposPending, pc0, ps0)
+      phases.push({ id: "skills", label: "Skills", script: ["set -e", ...l].join("\n"), runsOnRestart: true, statusStart: st, statusEnd: st })
+    }
+  }
+
   // ── clone repos ────────────────────────────────────────────────────────────
   if (project.repositories.length > 0) {
     const l: string[] = ["set -e", ...banner(`SETUP: CLONE REPOSITORIES (${project.repositories.length})`)]

package/src/script/skills.ts

@@ -0,0 +1,225 @@
+// Organization skills in a worker (Spunto Cloud RFC 0033).
+//
+// A *skill* is a directory holding a `SKILL.md` (plus whatever scripts and references sit next to
+// it). A *source* is a git repository that holds several of them under one path. This file turns a
+// list of sources — already resolved by the control plane: which ref, what to link by default, what
+// a project switched on or off — into one shell script that:
+//
+//  1. clones each source into `~/.spunto/skills/<id>/` (or fast-forwards an existing clone);
+//  2. links every skill it retains into each **discovery directory** the harness reads, one symlink
+//     per skill — never the whole directory, never over an entry that is already there;
+//  3. removes the links it posed on an earlier run and no longer wants, and only those.
+//
+// The same script serves the first boot (a setup phase) and every later refresh (before each
+// delegated task): it is idempotent, and what it did before is recorded in a ledger next to the
+// clones rather than guessed from the filesystem.
+//
+// It never fails. A skill that could not be fetched is a worse worker, not a broken one: every
+// failure is printed with a `[skills]` prefix and the script exits 0.
+
+/** Single-quotes a value for safe embedding in a shell command. */
+function shQuote(v: string): string {
+  return `'${v.replace(/'/g, `'\\''`)}'`
+}
+
+/** One source, as the control plane resolved it for this worker. */
+export type SkillSource = {
+  /**
+   * Stable identity, used as the clone's directory name. Restricted to `[A-Za-z0-9_-]` — anything
+   * else is refused rather than escaped, since it names a path the script removes.
+   */
+  id: string
+  /** What the log calls it (`owner/name`). Never a URL: it must not carry a credential. */
+  label: string
+  /**
+   * Where to clone or fetch from, credential included if there is one. `null` fetches through
+   * `origin` — for a hosted repository that is the worker's git credential helper.
+   *
+   * Overridable at run time through `skillFetchUrlEnv(index)`: a caller that must not write a
+   * credential into the command it runs (a command history is kept) passes it in the environment.
+   */
+  fetchUrl: string | null
+  /**
+   * What `origin` is left pointing at after a clone. Credential-free, so that whatever happens
+   * next in the worker (an agent fixing a skill and pushing a branch) goes through the credential
+   * helper as the member rather than reusing the organization's clone token. Defaults to
+   * `fetchUrl`.
+   */
+  originUrl?: string | null
+  /** Branch or tag. Empty → the remote's default branch. */
+  ref?: string | null
+  /** Directory inside the repository whose sub-directories are skills. Empty → the root. */
+  path?: string | null
+  /** Link a skill this source holds unless it is listed in `exclude`. */
+  linkByDefault: boolean
+  /** Always linked (wins over `exclude`). */
+  include?: string[]
+  /** Never linked, unless also in `include`. */
+  exclude?: string[]
+}
+
+export type SkillsScriptParams = {
+  sources: SkillSource[]
+  /**
+   * Where the harness discovers user-level skills, as **shell expressions** evaluated in the
+   * worker — `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills` for Claude Code. Evaluated there
+   * because only the worker knows its environment: a member can set `CLAUDE_CONFIG_DIR` as a
+   * secret. Trusted input (a harness pack's own declaration), interpolated as is.
+   */
+  discoveryDirs: string[]
+  /** The workspace user's home. */
+  homeDir?: string
+}
+
+/** Where clones live, relative to the user's home. Harness-neutral on purpose. */
+export const SKILLS_DIR = ".spunto/skills"
+
+/** The environment variable that overrides `sources[index].fetchUrl` at run time. */
+export function skillFetchUrlEnv(index: number): string {
+  return `SPUNTO_SKILL_FETCH_URL_${index}`
+}
+
+const SAFE_ID = /^[A-Za-z0-9_-]+$/
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+const SAFE_PATH = /^[A-Za-z0-9._/-]*$/
+/** A branch or tag. No leading `-`: it is passed to `git fetch` as a positional argument. */
+const SAFE_REF = /^[A-Za-z0-9._/][A-Za-z0-9._/-]*$/
+
+/**
+ * The script, run **as the workspace user** (never root: every file it creates is theirs).
+ *
+ * Returns `null` when there is nothing to do — no source *and* nothing to take down. Since the
+ * script cannot know the second half without running, a caller that had sources before should
+ * still run it with an empty list; `buildSkillsScript` only returns `null` when there are no
+ * discovery directories either.
+ */
+export function buildSkillsScript(params: SkillsScriptParams): string | null {
+  const homeDir = params.homeDir ?? "/home/vscode"
+  if (params.discoveryDirs.length === 0) return null
+
+  for (const s of params.sources) {
+    if (!SAFE_ID.test(s.id)) throw new Error(`Invalid skill source id: ${s.id}`)
+    if (s.path && (!SAFE_PATH.test(s.path) || s.path.split("/").includes(".."))) {
+      throw new Error(`Invalid skill source path: ${s.path}`)
+    }
+    if (s.ref && !SAFE_REF.test(s.ref)) throw new Error(`Invalid skill source ref: ${s.ref}`)
+    for (const u of [s.fetchUrl, s.originUrl]) {
+      if (u && u.startsWith("-")) throw new Error(`Invalid skill source URL for ${s.id}`)
+    }
+    for (const n of [...(s.include ?? []), ...(s.exclude ?? [])]) {
+      if (!SAFE_NAME.test(n)) throw new Error(`Invalid skill name: ${n}`)
+    }
+  }
+
+  const root = `${homeDir}/${SKILLS_DIR}`
+  const lines: string[] = [
+    `export HOME=${shQuote(homeDir)}`,
+    `export GIT_TERMINAL_PROMPT=0`,
+    `_sk_root=${shQuote(root)}`,
+    `_sk_ledger="$_sk_root/.links"`,
+    `mkdir -p "$_sk_root" && touch "$_sk_ledger" || { echo "[skills] ✗ cannot write $_sk_root"; exit 0; }`,
+    `_sk_want=$(mktemp)`,
+    `_sk_dirs=(${params.discoveryDirs.map((d) => `"${d}"`).join(" ")})`,
+    `_sk_ids=" "`,
+    ``,
+    // Clone or fast-forward one source. A ref that changed since the clone is a re-clone: a
+    // fast-forward between two branches means nothing.
+    `_sk_sync() {`,
+    `  local id="$1" label="$2" fetch="$3" origin="$4" ref="$5" dest="$_sk_root/$1"`,
+    `  if [ -d "$dest/.git" ] && [ "$(cat "$dest/.git/spunto-ref" 2>/dev/null)" != "$ref" ]; then`,
+    `    echo "[skills] $label: ref changed to '\${ref:-default branch}' — cloning again"`,
+    `    rm -rf "$dest"`,
+    `  fi`,
+    `  if [ ! -d "$dest/.git" ]; then`,
+    `    rm -rf "$dest"`,
+    `    if [ -z "$fetch" ]; then echo "[skills] ✗ $label: nothing to clone from"; return 1; fi`,
+    `    local b=(); [ -n "$ref" ] && b=(--branch "$ref")`,
+    `    if ! git clone --quiet --depth 1 "\${b[@]}" "$fetch" "$dest" 2>&1; then`,
+    `      echo "[skills] ✗ $label: clone failed — its skills are not linked"`,
+    `      rm -rf "$dest"`,
+    `      return 1`,
+    `    fi`,
+    `    if [ -n "$origin" ] && [ "$origin" != "$fetch" ]; then git -C "$dest" remote set-url origin "$origin"; fi`,
+    `    printf '%s' "$ref" > "$dest/.git/spunto-ref"`,
+    `  else`,
+    // A plain fetch on a shallow clone brings the new commits down to the existing boundary, so
+    // the fast-forward can be checked. Through the given URL first (the organization's read
+    // credential), then through origin (the credential helper) — a URL minted for the first boot
+    // has long expired on a restart.
+    `    local r="\${ref:-HEAD}" ok=""`,
+    `    if [ -n "$fetch" ] && git -C "$dest" fetch --quiet "$fetch" "$r" 2>/dev/null; then ok=1`,
+    `    elif git -C "$dest" fetch --quiet origin "$r" 2>&1; then ok=1; fi`,
+    `    if [ -z "$ok" ]; then`,
+    `      echo "[skills] ⚠ $label: fetch failed — keeping $(git -C "$dest" rev-parse --short HEAD)"`,
+    `    elif ! git -C "$dest" merge --ff-only --quiet FETCH_HEAD 2>&1; then`,
+    `      echo "[skills] ⚠ $label: cannot fast-forward (local changes?) — keeping $(git -C "$dest" rev-parse --short HEAD)"`,
+    `    fi`,
+    `  fi`,
+    // The exact commit in use, for the audit trail: these scripts run with the worker's secrets.
+    `  echo "[skills] $label @ \${ref:-default branch} → $(git -C "$dest" rev-parse HEAD)"`,
+    `}`,
+    ``,
+    // Link the retained skills of one source. A name already taken — by the dotfiles, by the
+    // member, by another source in this same run — is left alone and reported.
+    `_sk_link() {`,
+    `  local id="$1" sub="$2" def="$3" inc=" $4 " exc=" $5 " base="$_sk_root/$1" d name want dir t src`,
+    `  [ -n "$sub" ] && base="$base/$sub"`,
+    `  if [ ! -d "$base" ]; then echo "[skills] ⚠ $id: no directory '$sub' in the source"; return; fi`,
+    `  for d in "$base"/*/; do`,
+    `    [ -f "$d/SKILL.md" ] || continue`,
+    `    src="\${d%/}"; name=$(basename "$src"); want="$def"`,
+    `    case "$exc" in *" $name "*) want=0 ;; esac`,
+    `    case "$inc" in *" $name "*) want=1 ;; esac`,
+    `    [ "$want" = 1 ] || continue`,
+    `    for dir in "\${_sk_dirs[@]}"; do`,
+    `      mkdir -p "$dir" || continue`,
+    `      t="$dir/$name"`,
+    `      if grep -qxF "$t" "$_sk_want"; then echo "[skills] ⚠ $name: already linked from another source — skipped"; continue; fi`,
+    `      if [ -L "$t" ] && grep -qxF "$t" "$_sk_ledger"; then`,
+    `        [ "$(readlink "$t")" = "$src" ] || ln -sfn "$src" "$t"`,
+    `      elif [ -e "$t" ] || [ -L "$t" ]; then`,
+    `        echo "[skills] ⚠ $name: $t already exists — kept, not linked"; continue`,
+    `      else`,
+    `        ln -s "$src" "$t" || continue`,
+    `        echo "[skills] linked $name → $t"`,
+    `      fi`,
+    `      echo "$t" >> "$_sk_want"`,
+    `    done`,
+    `  done`,
+    `}`,
+    ``,
+  ]
+
+  params.sources.forEach((s, i) => {
+    const env = skillFetchUrlEnv(i)
+    const fetch = s.fetchUrl ?? ""
+    const origin = s.originUrl ?? s.fetchUrl ?? ""
+    lines.push(
+      `_sk_ids="\${_sk_ids}${s.id} "`,
+      `_sk_f=${shQuote(fetch)}; [ -n "\${${env}:-}" ] && _sk_f="$${env}"`,
+      `if _sk_sync ${shQuote(s.id)} ${shQuote(s.label)} "$_sk_f" ${shQuote(origin)} ${shQuote(s.ref ?? "")}; then`,
+      `  _sk_link ${shQuote(s.id)} ${shQuote((s.path ?? "").replace(/^\/+|\/+$/g, ""))} ${s.linkByDefault ? 1 : 0} ${shQuote((s.include ?? []).join(" "))} ${shQuote((s.exclude ?? []).join(" "))}`,
+      `fi`,
+    )
+  })
+
+  lines.push(
+    ``,
+    // Take down what this script posed before and no longer wants — only symlinks it recorded,
+    // so nothing a person put there is ever touched.
+    `while IFS= read -r _t; do`,
+    `  [ -n "$_t" ] || continue`,
+    `  grep -qxF "$_t" "$_sk_want" && continue`,
+    `  if [ -L "$_t" ]; then rm -f "$_t" && echo "[skills] unlinked $(basename "$_t")"; fi`,
+    `done < "$_sk_ledger"`,
+    `mv "$_sk_want" "$_sk_ledger"`,
+    // A source the organization removed: its clone goes too. Only directories, only by id.
+    `for _d in "$_sk_root"/*/; do`,
+    `  [ -d "$_d" ] || continue`,
+    `  _id=$(basename "$_d")`,
+    `  case "$_sk_ids" in *" $_id "*) ;; *) rm -rf "$_d" && echo "[skills] removed source $_id" ;; esac`,
+    `done`,
+    `exit 0`,
+  )
+  return lines.join("\n")
+}