rvlib-shipkit 0.35.4 → 0.35.6

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.35.6
+
+- **`shipkit init` furnishes an adopted repo with the folder-open half of the scaffold.** The day-one shape was written only for a dir with no commit history, so every repo wired AFTER it already existed got `repo.config.ts` and the scripts and no `.vscode/` at all: opening the folder started no watcher, and the hub the config advertises had no way in. `init` now writes `.vscode/settings.json` and `.vscode/tasks.json` on both its paths, the wiring run and the re-run, through the same writers and the same templates the start scaffold uses. The split it holds: a file that changes no output of any command lands on adopt, and anything saying what the repo IS (`tsconfig.json`, `src/index.ts`) or what an agent may DO in it (the verify skill, the `.claude/` policy files, the `agent/` wiki, the `.rv-reflections/` seed) still needs an explicit caller, because a repo with a history of its own already answered those. Create only, so a `.vscode/` a repo was forked with survives byte for byte, and a second run writes nothing and says so. The advertised port is resolved from `repo.config.ts` (`serve.port`, else derived from the config name), which is where the hub reads it, rather than from the folder name or a stale `package.json`. A `.vscode` path that cannot hold the two files (a read only tree, a path that is a file) costs one WARN naming the errno: this write runs after `repo.config.ts` is on disk and before the publish chain, and it is the least important thing the verb does, so it never kills the run.
+
+## 0.35.5
+
+- **The `TaskDef.inputs` doc comment stated only half the safety rule.** It said undeclared means never cached, so forgetting costs speed and never correctness, which is true for forgetting a whole task and false for the mistake that actually ships a false green: a list MISSING a path the command reads. The key cannot move when that path changes, so the answer replays over a tree it no longer describes. Observed twice in the field in one day. The comment now carries the asymmetry, names `['.']` as the declaration that cannot under declare, and says that a task carries no code closure, so the script it runs belongs in `inputs` too.
+- **`shipkit release` scopes its dirt check exactly like `shipkit bump`.** `bump` examined the released unit plus every package.json and lockfile a version commit can touch; `release` examined the WHOLE worktree, refused, and then named `shipkit release` as the fix, which refuses identically. Several agents share one checkout here, so a neighbour editing an unrelated package was enough to wedge a release with no way forward that the message described. The reason to refuse at all is unchanged and still applies inside the scope: `npm publish` packs the WORKING TREE rather than the commit, so a half written file inside the unit ships under a tag that describes something else. Dirt in another unit reaches neither the tarball nor the tag, and the refusal now says what it examined.
+
 ## 0.35.4
 
 - **The imports refusal did not follow tsconfig `extends`, so a correctly configured repo went red and was told to add a key it already had.** Inheriting `paths` from a base config is the more common way to carry them, and only `references` was handled. `extends` is now followed (relative and node-resolved, chains and cycles included), and a mapping counts only when its TARGET is on disk: `"src/*": ["./packages/core/src/*"]` maps the prefix and resolves nothing. A package prefix is no longer accepted on the package DIRECTORY existing either, since a stale installed copy missing the file is the same false green one level up. `baseUrl` is no longer proof at all: tsc follows one, but rollup, esbuild and vite do not resolve a bare specifier through it, and the field failure this guard exists for was a rollup one. A multi-segment root (`packages/core`) is named as itself rather than as `packages`.

package/package.json

@@ -1,6 +1,7 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.35.4",
+    "version": "0.35.6",
+    "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
     "type": "module",

package/src/cli/cmd_Init.ts

@@ -8,7 +8,7 @@ export class InitCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'wire THE CURRENT DIRECTORY as a shipkit repo, like git init: cwd only, never creates a project dir. scaffolds repo.config.ts + ci/check/contracts package.json scripts, prints how the floor resolved, and runs the bootstrap chain around it: git init, then first commit + PRIVATE github repo + push once the scaffold is in. Idempotent on an already-wired repo. To create or adopt ~/dev/<name> from anywhere: `shipkit start <name>`',
+        description: 'wire THE CURRENT DIRECTORY as a shipkit repo, like git init: cwd only, never creates a project dir. scaffolds repo.config.ts + ci/check/contracts package.json scripts + the create-only .vscode/ that starts the watchers and the hub on folder open, prints how the floor resolved, and runs the bootstrap chain around it: git init, then first commit + PRIVATE github repo + push once the scaffold is in. Idempotent on an already-wired repo. To create or adopt ~/dev/<name> from anywhere: `shipkit start <name>`',
         examples: [
             ['wire the repo you are standing in', 'shipkit init'],
             ['local git and the first commit, never touch github', 'shipkit init --no-github'],

package/src/core/run-check.ts

@@ -77,8 +77,14 @@ export type CheckOpts = {
  *  check's name AND its path), because the id an operator types is whichever
  *  one they last saw on the wire. */
 export function matchesOnly(only: string[] | undefined, ...names: string[]): boolean {
-    if (only == null || only.length === 0) return true
-    return only.some((want) => names.some((n) => n.toLowerCase() === want.toLowerCase()))
+    if (!isNarrowed(only)) return true
+    return only!.some((want) => names.some((n) => n.toLowerCase() === want.toLowerCase()))
+}
+
+/** did the operator narrow this run? The ONE reading of `--only` everywhere: an
+ *  empty list is not a selection, it is the absence of one. */
+export function isNarrowed(only: string[] | undefined): boolean {
+    return only != null && only.length > 0
 }
 
 export type CheckRun = {
@@ -210,8 +216,11 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
         // and that can sit red for months with nothing wrong, is not part of
         // that answer at any interval. `shipkit check` still runs it, and
         // naming it in `--only` still runs it, so opting out is never a way to
-        // make a check unreachable.
-        if (o.gateOnly === true && !d.gate && o.only == null) continue
+        // make a check unreachable. "not narrowed" is an EMPTY list as much as
+        // an absent one: the CLI's --only is an Option.Array defaulting to [],
+        // so a `== null` test here reads every plain gate run as narrowed and
+        // opts nothing out (matchesOnly above uses the same predicate).
+        if (o.gateOnly === true && !d.gate && !isNarrowed(o.only)) continue
         const blocking = d.blocking ?? c.checkDefaults?.blocking
         if (blocking == null) undeclared.push(rel)
         if (o.onlyBlocking === true && blocking !== true) continue

package/src/core/task-runner.ts

@@ -32,8 +32,14 @@ export type TaskDef = {
     timeoutMs?: number
     /** CONTENT population: the repo-relative paths this task reads. Declaring
      *  them is what makes the task keyable (ledger/git-key.ts). Undeclared is
-     *  the DEFAULT and means never cached, so forgetting costs speed and never
-     *  correctness. Declaring both this and `ttl` is a registration failure. */
+     *  the DEFAULT and means never cached, so forgetting a whole task costs
+     *  speed and never correctness. A list MISSING a path the command reads is
+     *  the one that costs correctness: the key cannot move when that path
+     *  changes, so the answer replays over a tree it no longer describes. Over
+     *  declaring costs a re-run, under declaring is a false green, and `['.']`
+     *  is the whole work tree and cannot under declare. A task carries no code
+     *  closure, so the script it runs belongs in here too.
+     *  Declaring both this and `ttl` is a registration failure. */
     inputs?: string[]
     /** WORLD population: this task reads the network, a keychain, $PATH or the
      *  clock, so nothing on disk describes its answer and a clean pass is

package/src/init-repo.ts

@@ -15,6 +15,8 @@ import { reportToMotherhome } from './core/motherhome.ts'
 import { ensureGitRepo, publishRepo, type Run } from './git-bootstrap.ts'
 import { defineRepo, loadRepoConfig, resolveFloor } from './repo-config.ts'
 import { gitignorePolicy } from './rules/SK004-gitignore-policy.ts'
+import { editorErgonomics } from './scaffold/project-scaffold.ts'
+import { defaultHubPort } from './serve/hub-port.ts'
 
 // This lands as SOURCE in the repo being wired, so its comments answer to that
 // repo's comment style, not to this file's. Dash punctuation is banned there
@@ -94,6 +96,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
         // the repos that need ONE WAY IN most are the ones that already exist,
         // so a re-run REPAIRS rather than only seeding a fresh checkout
         await repairOneWayIn(root, cfg, p)
+        furnishEditor(root, cfg.name, cfg.serve?.port ?? defaultHubPort(cfg.name), p)
         const mh = reportToMotherhome(root, cfg)
         if (mh.note != null) p(mh.note)
         if (wired && opts.noPublish !== true) await publishRepo(root, { github: opts.github, gh: opts.gh, print: p })
@@ -127,6 +130,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     const g = await gitignorePolicy.fix!({ root, config: defineRepo({ name }) })
     p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
     await repairOneWayIn(root, defineRepo({ name }), p)
+    furnishEditor(root, name, defaultHubPort(name), p)
     // what the gate actually runs, in ONE line: a thin floor must be seen at
     // init time rather than discovered after a bad commit slipped through.
     // The per-task resolution is diagnostics, and a `skip:` naming a script
@@ -157,6 +161,29 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     return 0
 }
 
+/** the folder-open story, on the adopt path as well as the start one.
+ *
+ *  `start` scaffolds the whole day-one shape, but only for a dir with no
+ *  commit history, so every repo that already existed when it was wired got
+ *  repo.config.ts and the scripts and no .vscode/ at all: opening the folder
+ *  started nothing, and the hub the config advertises had no way in. These two
+ *  files are the only half of that scaffold an adopted repo can be handed
+ *  unasked, because they change no output of any command (project-scaffold.ts
+ *  owns the line). Create-only, so a .vscode/ the repo brought with it wins. */
+function furnishEditor(root: string, name: string, port: number, p: (line: string) => void): void {
+    // the least important thing init does, and it runs AFTER repo.config.ts is
+    // on disk: an unwritable .vscode (a read-only tree, a path that is a file)
+    // must not abort the run before the publish chain, and must not pass in
+    // silence either
+    try {
+        const wrote = editorErgonomics(root, { name, port })
+        if (wrote.length > 0) p(`ok: ${wrote.join(' + ')} written — opening the folder starts the watchers and the hub on ${port}`)
+        else p('ok: .vscode/ already yours, left untouched')
+    } catch (e) {
+        p(`WARN no .vscode/ here: ${e instanceof Error ? e.message : String(e)} — opening the folder starts nothing, everything else landed`)
+    }
+}
+
 /** ONE WAY IN, both halves, through the SAME fixers `shipkit check --fix` runs
  *  (build/shipkit.md). Nothing here is a second implementation: rule SK001
  *  routes the package.json scripts, rule SK013 writes the harness policy, and

package/src/release/run-release.ts

@@ -11,6 +11,7 @@ import { join } from 'path'
 import { runCi } from '../core/run-ci.ts'
 import { extractChangelogSection } from './changelog.ts'
 import { deriveRemote, dirtyPaths, git, remoteTagState, tagExistsLocally, type RemoteTagState } from './git-facts.ts'
+import { releaseScope } from './release-scope.ts'
 import { npmPublishArgv, unitBlockers } from './unit-gate.ts'
 import { formatUnitError, resolveUnits, unitById, type ReleaseUnit } from './units.ts'
 import type { RepoConfig } from '../repo-config.ts'
@@ -172,9 +173,23 @@ export async function releaseUnit(root: string, config: RepoConfig, unit: Releas
     if (cur.code !== 0) blockers.push('not a git repository')
     else if (cur.out !== branch) blockers.push(`releases ship from '${branch}', HEAD is on '${cur.out}'`)
 
-    const dirty = dirtyPaths(root, config)
-    if (dirty !== '' && o.allowDirty !== true)
-        blockers.push(`working tree not clean (--allow-dirty overrides):\n${dirty.split('\n').slice(0, 10).join('\n')}`)
+    // scoped exactly like `bump`, and for the same reason: `npm publish` packs
+    // the WORKING TREE rather than the commit, so dirt INSIDE what ships can
+    // put a half written file under a tag that describes something else. Dirt
+    // in another unit reaches neither this tarball nor this tag. Checking the
+    // whole tree here made `release` refuse what `bump` allows, and then name
+    // `shipkit release` as the fix, which refuses identically: several agents
+    // share this checkout, so a neighbour editing an unrelated package was
+    // enough to wedge a release with no way forward that the message named.
+    // the sibling units matter to the SCOPE: a version write rewrites the
+    // rvlib range in every dependent's package.json, so those paths are inside
+    // this release even though they are outside this unit
+    const scope = releaseScope(root, resolveUnits(root, config).units, [unit])
+    const dirty = dirtyPaths(root, config, scope.specs ?? undefined)
+    if (dirty !== '' && o.allowDirty !== true) {
+        blockers.push(`uncommitted changes in ${scope.describe} (--allow-dirty overrides):\n${dirty.split('\n').slice(0, 10).join('\n')}`)
+        if (scope.specs != null) blockers.push('dirt elsewhere in the worktree is deliberately ignored, it cannot reach this tarball or this tag')
+    }
     if (o.skipUnitGate !== true) blockers.push(...unitBlockers(root, config, unit))
 
     let alreadyPublished = false

package/src/scaffold/project-scaffold.ts

@@ -99,15 +99,51 @@ function put(root: string, rel: string, body: string): boolean {
     return true
 }
 
+/** the ERGONOMIC half of the day-one shape: the two files that decide what
+ *  happens when the folder is opened in vscode, and nothing else. */
+export const ERGONOMIC_FILES = ['.vscode/settings.json', '.vscode/tasks.json'] as const
+
+export type ErgonomicsOpts = {
+    /** repo name, substituted into the templates */
+    name: string
+    /** the port the hub actually listens on, resolved by the caller from the
+     *  repo config (`serve.port`, else the name-derived default), so the task
+     *  advertises a url something answers on */
+    port: number
+}
+
+/** the folder-open half of the scaffold, split out because it is the ONLY
+ *  half an ADOPTED repo can be given unasked.
+ *
+ *  Everything else the day-one shape writes says what the repo IS (a tsconfig,
+ *  a src/index.ts) or what an agent may DO in it (the verify skill, the
+ *  .claude/ policy files), and a repo with a history of its own already
+ *  answered those. A tasks file and an editor settings file change no output
+ *  of any command: they decide what vscode starts when the folder opens, and
+ *  a repo where that starts nothing has no folder-open story at all.
+ *
+ *  Create-only, like every other writer here: an adopted repo often carries a
+ *  .vscode/ from whatever it was forked from, and that one wins byte for
+ *  byte. Returns the paths it wrote, so a caller can say "already current"
+ *  when it wrote none. */
+export function editorErgonomics(root: string, opts: ErgonomicsOpts): string[] {
+    const vars = { NAME: opts.name, PORT: String(opts.port), DATE: '' }
+    const written: string[] = []
+    if (put(root, '.vscode/settings.json', template('vscode-settings.json', vars))) written.push('.vscode/settings.json')
+    if (put(root, '.vscode/tasks.json', template('vscode-tasks.json', vars))) written.push('.vscode/tasks.json')
+    return written
+}
+
 export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
     const p = opts.print ?? console.log
     // the hub resolves its port from the CONFIG name, which init takes from
     // package.json — a dir whose folder name differs would otherwise get a
     // tasks.json advertising a port nothing listens on
     const configName = packageName(root) ?? opts.name
+    const port = defaultHubPort(configName)
     const vars = {
         NAME: opts.name,
-        PORT: String(defaultHubPort(configName)),
+        PORT: String(port),
         DATE: opts.today ?? new Date().toISOString().slice(0, 10),
     }
     const written: string[] = []
@@ -116,8 +152,8 @@ export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
 
     write('src/index.ts', 'export {}\n')
     write('tsconfig.json', template('tsconfig.json', vars))
-    write('.vscode/settings.json', template('vscode-settings.json', vars))
-    write('.vscode/tasks.json', template('vscode-tasks.json', vars))
+    for (const rel of editorErgonomics(root, { name: opts.name, port })) written.push(rel)
+    for (const rel of ERGONOMIC_FILES) if (!written.includes(rel)) skipped.push(rel)
     write('.claude/skills/verify/SKILL.md', template('verify-skill.md', vars))
     // a permission grant and a git-history policy are decisions about someone
     // else's repo, so they land only for a caller that declared a house, and