chamba 0.3.1 → 0.4.0

package/templates/git-readonly-wrapper.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+// =============================================================================
+// git-readonly-wrapper.mjs -- Read-only git wrapper for strict mode
+// Baked into the container image at /usr/local/share/chamba/git-readonly.
+// startup.mjs symlinks /usr/local/bin/git -> this file when git_mode=strict.
+// PATH puts /usr/local/bin before /usr/bin so this is invoked when an agent
+// runs `git`. Allowed subcommands forward to /usr/bin/git unchanged; blocked
+// ones print a clear error and exit non-zero.
+//
+// Threat model: guardrails for cooperative agents, not adversarial containment.
+// /usr/bin/git remains accessible by absolute path; remote ops stay blocked at
+// the gitconfig protocol layer regardless of which binary is invoked.
+//
+// The classifier is exported for unit testing. Pure Node built-ins, no deps.
+// =============================================================================
+
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const REAL_GIT = "/usr/bin/git";
+
+// -- Read-only global actions: print and exit, no subcommand needed -----------
+const READ_ONLY_GLOBAL_ACTIONS = new Set(["--version", "--help", "-h", "--html-path", "--man-path", "--info-path"]);
+
+// -- Global flags that consume the next argv element as their value -----------
+const TWO_ARG_GLOBALS = new Set(["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--super-prefix", "--attr-source"]);
+
+// -- Subcommands that are unconditionally read-only ---------------------------
+const READ_SUBCOMMANDS = new Set([
+    "status",
+    "log",
+    "show",
+    "diff",
+    "blame",
+    "reflog",
+    "rev-parse",
+    "rev-list",
+    "describe",
+    "cat-file",
+    "name-rev",
+    "fsck",
+    "shortlog",
+    "grep",
+    "count-objects",
+    "var",
+    "help",
+    "version",
+    "ls-files",
+    "ls-tree",
+    "merge-base",
+    "for-each-ref",
+    "show-ref",
+    "symbolic-ref",
+    "check-ignore",
+    "check-attr",
+    "check-mailmap",
+    "check-ref-format",
+    "whatchanged",
+    "cherry",
+    "range-diff",
+    "verify-commit",
+    "verify-tag",
+    "annotate",
+    "instaweb",
+    "diff-tree",
+    "diff-index",
+    "diff-files",
+]);
+
+// -- branch/tag flags that indicate mutation; block on any match --------------
+const BRANCH_MUTATING_FLAGS = new Set([
+    "-d",
+    "-D",
+    "-m",
+    "-M",
+    "-c",
+    "-C",
+    "--delete",
+    "--move",
+    "--copy",
+    "--set-upstream",
+    "--set-upstream-to",
+    "--unset-upstream",
+    "--edit-description",
+    "--create-reflog",
+]);
+
+const TAG_MUTATING_FLAGS = new Set([
+    "-d",
+    "-D",
+    "-m",
+    "-a",
+    "-s",
+    "-u",
+    "-f",
+    "--delete",
+    "--message",
+    "--annotate",
+    "--sign",
+    "--local-user",
+    "--cleanup",
+    "--force",
+]);
+
+// -- config flags: explicit read/write markers + flags that consume the next arg ----
+const CONFIG_READ_FLAGS = new Set([
+    "--get",
+    "--get-all",
+    "--get-regexp",
+    "--get-urlmatch",
+    "--get-color",
+    "--get-colorbool",
+    "--list",
+    "-l",
+    "--show-origin",
+    "--show-scope",
+    "--name-only",
+]);
+const CONFIG_WRITE_FLAGS = new Set([
+    "--unset",
+    "--unset-all",
+    "--add",
+    "--replace-all",
+    "--remove-section",
+    "--rename-section",
+    "-e",
+    "--edit",
+]);
+// Flags that take their next arg as a value -- skip the value when counting tokens.
+// --file/-f/--blob = scope; --type = value coercion; --default = fallback for --get.
+const CONFIG_TWO_ARG_FLAGS = new Set(["--file", "-f", "--blob", "--type", "--default"]);
+// Keys whose write form is allowed in strict mode. Narrow by design: each entry must be
+// safe (cannot escalate to remote ops or weaken protocol.allow). core.hooksPath unblocks
+// `pnpm install` for repos whose prepare script points git at a tracked hooks directory.
+// Compared lowercased: git treats section/variable names case-insensitively.
+const CONFIG_WRITE_ALLOWLIST = new Set(["core.hookspath"]);
+
+// -- remote: block these subactions, allow the rest (default = list) ----------
+const REMOTE_MUTATING_ACTIONS = new Set(["add", "remove", "rm", "rename", "set-url", "prune", "update", "set-head", "set-branches"]);
+
+// -- stash: only these subactions are read-only; bare `git stash` mutates -----
+const STASH_READ_ACTIONS = new Set(["list", "show"]);
+
+// -- worktree: only `list` is read-only ---------------------------------------
+const WORKTREE_READ_ACTIONS = new Set(["list"]);
+
+// -- notes: list/show are read; bare `git notes` defaults to list -------------
+const NOTES_READ_ACTIONS = new Set(["list", "show", "get-ref"]);
+
+// -- bisect: log/view are read; everything else mutates the bisect state ------
+const BISECT_READ_ACTIONS = new Set(["log", "view"]);
+
+/**
+ * Walk argv left-to-right and find the first non-flag token (the subcommand).
+ * Skips git's global option flags, including ones whose value is in the next argv slot.
+ * Returns { subcmd, rest } where rest is the args after the subcommand.
+ */
+export function findSubcommand(argv) {
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        if (!arg.startsWith("-")) {
+            return { subcmd: arg, rest: argv.slice(i + 1) };
+        }
+        if (TWO_ARG_GLOBALS.has(arg)) {
+            // -c key=value, -C path, --git-dir path, etc.
+            i += 2;
+            continue;
+        }
+        // --foo=bar, --bare, --no-pager, --paginate, etc. - one-arg
+        i += 1;
+    }
+    return { subcmd: null, rest: [] };
+}
+
+/**
+ * Classify a git invocation under strict mode.
+ * Returns { allow: true } or { allow: false, reason: string }.
+ * Pure function - exported for unit testing without forking.
+ */
+export function classify(argv) {
+    // Read-only global actions (--version, --help, etc.) short-circuit.
+    for (const a of argv) {
+        if (READ_ONLY_GLOBAL_ACTIONS.has(a)) return { allow: true };
+        if (a.startsWith("--list-cmds=")) return { allow: true };
+    }
+
+    const { subcmd, rest } = findSubcommand(argv);
+
+    // Bare `git` (no subcommand) prints usage - read-only.
+    if (subcmd === null) return { allow: true };
+
+    if (READ_SUBCOMMANDS.has(subcmd)) return { allow: true };
+
+    if (subcmd === "branch") {
+        for (const a of rest) {
+            if (BRANCH_MUTATING_FLAGS.has(a)) return blocked(`branch ${a}`);
+        }
+        return { allow: true };
+    }
+
+    if (subcmd === "tag") {
+        for (const a of rest) {
+            if (TAG_MUTATING_FLAGS.has(a)) return blocked(`tag ${a}`);
+        }
+        return { allow: true };
+    }
+
+    if (subcmd === "config") {
+        // Explicit write flags take precedence over everything else.
+        for (const a of rest) {
+            if (CONFIG_WRITE_FLAGS.has(a)) return blocked(`config ${a}`);
+        }
+        // Explicit read flags are an unconditional allow.
+        for (const a of rest) {
+            if (CONFIG_READ_FLAGS.has(a)) return { allow: true };
+        }
+        // Otherwise count non-flag tokens after the subcommand:
+        //   `config <key>`           -> 1 token  -> read
+        //   `config <key> <value>`   -> 2 tokens -> write (allowed only if key is in allowlist)
+        // Scope flags (--system, --global, ...) are flags and don't count.
+        let nonFlagCount = 0;
+        let firstKey = null;
+        for (let i = 0; i < rest.length; i++) {
+            const a = rest[i];
+            if (a.startsWith("-")) {
+                if (CONFIG_TWO_ARG_FLAGS.has(a)) i++; // also consume its value
+                continue;
+            }
+            nonFlagCount++;
+            if (nonFlagCount === 1) firstKey = a;
+            if (nonFlagCount >= 2) {
+                if (firstKey !== null && CONFIG_WRITE_ALLOWLIST.has(firstKey.toLowerCase())) return { allow: true };
+                return blocked("config (write)");
+            }
+        }
+        return { allow: true };
+    }
+
+    if (subcmd === "stash") {
+        const action = firstNonFlag(rest);
+        if (action !== null && STASH_READ_ACTIONS.has(action)) return { allow: true };
+        return blocked(action ? `stash ${action}` : "stash");
+    }
+
+    if (subcmd === "remote") {
+        const action = firstNonFlag(rest);
+        if (action !== null && REMOTE_MUTATING_ACTIONS.has(action)) return blocked(`remote ${action}`);
+        return { allow: true };
+    }
+
+    if (subcmd === "worktree") {
+        const action = firstNonFlag(rest);
+        if (action !== null && WORKTREE_READ_ACTIONS.has(action)) return { allow: true };
+        return blocked(action ? `worktree ${action}` : "worktree");
+    }
+
+    if (subcmd === "notes") {
+        const action = firstNonFlag(rest);
+        if (action === null || NOTES_READ_ACTIONS.has(action)) return { allow: true };
+        return blocked(`notes ${action}`);
+    }
+
+    if (subcmd === "bisect") {
+        const action = firstNonFlag(rest);
+        if (action !== null && BISECT_READ_ACTIONS.has(action)) return { allow: true };
+        return blocked(action ? `bisect ${action}` : "bisect");
+    }
+
+    return blocked(subcmd);
+}
+
+function firstNonFlag(args) {
+    for (const a of args) {
+        if (!a.startsWith("-")) return a;
+    }
+    return null;
+}
+
+function blocked(label) {
+    return {
+        allow: false,
+        reason: `git: '${label}' blocked in strict mode (read-only). Switch git mode via 'chamba' menu > Settings > Git mode.`,
+    };
+}
+
+// Skip the runtime invocation when imported (e.g. by the test suite). The wrapper is normally
+// invoked through the symlink at /usr/local/bin/git, so a literal argv[1] vs import.meta.url
+// comparison wouldn't match -- realpathSync resolves the symlink before comparing.
+function detectIsMain() {
+    if (!process.argv[1]) return false;
+    try {
+        return fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
+    } catch {
+        return false;
+    }
+}
+const isMain = detectIsMain();
+
+if (isMain) {
+    const result = classify(process.argv.slice(2));
+    if (!result.allow) {
+        process.stderr.write(`${result.reason}\n`);
+        process.exit(1);
+    }
+    const child = spawnSync(REAL_GIT, process.argv.slice(2), { stdio: "inherit" });
+    process.exit(child.status ?? 1);
+}

package/templates/npmrc

@@ -0,0 +1,2 @@
+store-dir=/home/devuser/.local/share/pnpm/store
+package-import-method=copy

package/templates/pnpm-config.yaml

@@ -0,0 +1,9 @@
+# pnpm global config. pnpm 11+ reads its settings from here (~/.config/pnpm/config.yaml),
+# no longer from ~/.npmrc. Keys are camelCase, unlike the kebab-case equivalents in .npmrc.
+#
+# storeDir pins the global store onto a bind-mounted, same-device cache so pnpm never falls back
+# to creating a .pnpm-store inside the mounted /workspace. packageImportMethod=copy avoids
+# cross-filesystem hardlink failures. The matching ~/.npmrc keeps this working for anyone who
+# pins an older pnpm via packageManager (pnpm <= 10 still reads .npmrc).
+storeDir: /home/devuser/.local/share/pnpm/store
+packageImportMethod: copy

package/templates/runtime-constants.mjs

@@ -0,0 +1,18 @@
+// =============================================================================
+// runtime-constants.mjs -- Constants shared between container-side runtime
+// scripts and the chamba CLI build.
+//
+// Container-side scripts (startup.mjs, startup-git-mode.mjs) cannot import
+// from src/lib/constants.ts since the TS source isn't shipped to the image.
+// Keep this file plain ESM and import it from both sides; src/lib/constants.ts
+// re-exports the values so TS callers stay typed.
+// =============================================================================
+
+export const GIT_MODE = Object.freeze({
+    strict: "strict",
+    local: "local",
+    unrestricted: "unrestricted",
+});
+
+export const GIT_WRAPPER_PATH = "/usr/local/bin/git";
+export const GIT_WRAPPER_SOURCE = "/usr/local/share/chamba/git-readonly";

package/templates/skills/chamba-statusline/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: chamba-statusline
+description: Explain where a session's status lives in chamba - the strip in the web interface, the snapshot behind it, and the context-usage helper. Use when the user mentions the status line, asks why the terminal has none, asks what the strip above the composer means, or wants a status line of their own.
+---
+
+# chamba-statusline: Where a session's status is
+
+In chamba there is no status line in the terminal. The script Claude Code runs for one is installed and does run, but it prints nothing: it writes a snapshot file instead, and chamba draws the status from that file in the web interface, as a strip above the composer.
+
+That is the answer to most questions this skill gets. The rest of it is the detail behind it, and what to do when the user wants something different.
+
+**Important constants:**
+- The chamba script is baked into the image at `{{statusline_path}}` (read-only, root-owned).
+- Claude reads its status line config from `~/.claude/settings.json` (`statusLine.command`).
+- Snapshots are written to `~/.claude/context-usage/<session_id>.json`, one per conversation, on every prompt render.
+
+## Step 1 - The strip, which is where the numbers are
+
+The web interface shows the attached session's status in one line between the terminal and the composer. Four segments, left to right, separated by a mid-dot:
+
+1. **Model** - the display name Claude Code reports, with any trailing parenthetical (such as "(1M context)") trimmed, and the reasoning effort beside it.
+2. **Context** - tokens held, then the size of the window they sit in, a bar, and the percentage. The size half is dropped when Claude Code does not report a window size. The bar turns yellow as the window fills and red near the top.
+3. **Quota** - what is LEFT of the five-hour rate-limit window, as a bar and a percentage, with the time until it recharges beside it. It is an energy meter: full and green when fresh, yellow at half, red near empty. Absent on free accounts and before the first API response.
+4. **Claude Code** - the installed CLI version.
+
+The strip belongs to the session it is drawn for, and only a claude session has one - the snapshot is a Claude Code feature, so a codex or opencode tab has no strip at all.
+
+## Step 2 - The snapshot behind it, and the helper
+
+The script at `{{statusline_path}}` is what makes any of this exist. Claude Code runs it on every prompt render and hands it the session's state on stdin; the script parses it, resolves the pid of the claude process it was run by, and writes a small JSON file. Fields: `session_id`, `claude_pid`, `claude_pid_start`, `updated_at`, `context_tokens`, `context_used_pct`, `context_window_size`, `model`, `effort`, `quota_left_pct`, `quota_resets_at`, `version`.
+
+Two things read those files:
+- The web interface, which matches a snapshot to a session by that pid and draws the strip from it.
+- The `context-usage` command, which is how an agent inspects its own context and quota from the terminal. Run it rather than reading the files by hand; the `context-usage` skill covers the output.
+
+If the user wants the numbers without the browser, `context-usage` is the answer.
+
+## Step 3 - When the user wants a status line of their own
+
+The chamba script prints nothing on purpose: a status line is redrawn inside the conversation, so in a browser it scrolls away with the output and costs a row of the terminal every prompt. The strip is the same information somewhere it stays put.
+
+A user who works in the terminal and wants a visible line back can have one - by pointing Claude Code at their own script. Explain the trade first (a custom script replaces chamba's, and chamba's is what writes the snapshots the strip and `context-usage` read), then offer to write one that renders a line AND keeps the snapshot side effect: copy `{{statusline_path}}` and add rendering to it, rather than starting from nothing.
+
+### Permissions: you perform the edits
+
+Every action below involves editing `~/.claude/settings.json` and/or writing scripts under `~/.claude/`. **You** make those edits directly with the `Edit` and `Write` tools - do not tell the user to run the change themselves.
+
+If write access to those paths is not pre-approved, Claude Code will surface its standard permission prompt. **That prompt is the expected approval flow, not a refusal signal** - go ahead and call the tool, and the user will grant permission when they see it. Do not apologise for "lacking permission" and do not redirect the work back to the user.
+
+### Inspect what is configured now
+
+Read `~/.claude/settings.json` (treat a missing file or unparseable JSON as `{}`), look at `.statusLine.command`, and classify:
+
+- **default-by-omit** - no `statusLine` field. chamba injects its own at the next session start; the running session has none yet.
+- **chamba-default** - `statusLine.command` equals `{{statusline_path}}`.
+- **custom** - anything else. Say the exact path.
+
+### Fork and edit
+
+Never edit `{{statusline_path}}` directly - it is root-owned and read-only inside the container.
+
+1. Copy the script to a writable location:
+   ```bash
+   cp {{statusline_path}} ~/.claude/statusline.sh
+   chmod +x ~/.claude/statusline.sh
+   ```
+2. Ask what the line should show, then edit `~/.claude/statusline.sh`. Keep the snapshot write at the end of it, whatever else changes: the strip and `context-usage` both stop working without it.
+3. Point `statusLine.command` at `~/.claude/statusline.sh` in `~/.claude/settings.json`, preserving every other field.
+4. Tell the user to restart Claude - a status line change takes effect at the next session.
+
+### Revert to the chamba default
+
+Set `statusLine.command` back to `{{statusline_path}}`. Do not delete the user's own script; just stop pointing at it, and say it is still on disk. Restart Claude.
+
+## Notes
+
+- Always preserve other fields in `settings.json` when editing. The file may hold unrelated user settings.
+- If `settings.json` does not exist or is unparseable, create it fresh as `{ "statusLine": { ... } }`.
+- A custom script must use only the fields documented in the official Claude Code statusline reference: https://code.claude.com/docs/en/statusline#available-data - consult that page for the full list of available JSON fields, their types, nullability, and conditional presence.

package/templates/skills/context-usage/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: context-usage
+description: Report the current session's context-window and rate-limit (quota) usage. Use whenever the user asks how much context, tokens, or quota is used or left, how full the context window is, or when the rate limit resets.
+---
+
+# context-usage: Report context and quota usage
+
+In a chamba container you CAN see your own context-window and rate-limit usage.
+The status line script chamba installs writes a per-session snapshot on every prompt render (it renders nothing in the terminal - the web interface draws a strip from the same file); a bundled helper reads it back.
+
+## Procedure
+
+1. Run:
+
+   ```bash
+   context-usage
+   ```
+
+   Example output:
+
+   ```
+   session: 78b4025b-... (this session, updated 3s ago)
+   context: 70.8k tokens (7% of 1M window)
+   quota:   84% remaining, resets in 21m
+   model:   Fable 5 (effort high)
+   ```
+
+2. Answer in ONE short line, in exactly this shape:
+
+   > Context: 70.8k tokens (7%) - quota: 84% left, resets in 21m.
+
+   If the user asked only about context or only about quota, answer with just that half.
+   Expand beyond one line only when the user explicitly asks for more detail.
+   Do not add commentary, interpretation, or advice.
+
+3. Caveats are the exception, not the norm.
+   The `(this session, ...)` marker on the session line means the snapshot is guaranteed to be this session's own - say nothing about it.
+   Only when the marker is absent AND the output contains a `warning:` line, append one short sentence relaying that warning.
+
+## Interpretation notes
+
+- The snapshot reflects usage as of the moment the current prompt was submitted; tokens consumed during the in-flight turn are not included yet.
+  No need to mention this unless asked.
+- The `quota` line refers to the 5-hour rate-limit window and is absent when Claude Code did not report rate-limit data.
+
+## Fallback
+
+If the `context-usage` command is not found, read the snapshot directly: list `~/.claude/context-usage/*.json`, pick the most recently modified file, and interpret its fields - `context_tokens`, `context_used_pct`, `context_window_size`, `model`, `effort`, `quota_left_pct`, `quota_resets_at` (epoch seconds), `updated_at` (epoch seconds), `version`, `session_id`.
+
+If the command does not exist AND there are no snapshot files either, the container image predates this feature.
+In that case tell the user to rebuild the image: start a new chamba session on the host and accept the rebuild prompt.
+
+If the command exists but no snapshot files do, no Claude session in this container has rendered a prompt yet; say so rather than guessing values.

package/templates/skills/web-pane/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: web-pane
+description: Publish an HTML page into the web pane beside the terminal - and ask questions with a form in it. Use when the user says "show me", "as a page", "in the pane", "publish this", "write it up", or asks for a plan, a table, a comparison, a diagram, a report, or a long explanation; and whenever you need to ask something with more options or structure than your question tooling holds.
+---
+
+# web-pane: publish a page, and ask with it
+
+The web pane is the panel beside the terminal in the chamba web interface. You publish a standalone HTML file into it and it appears at once, as a chip in the bar above the pane; the user clicks the chip to read it.
+
+Publish when the answer is bigger than the terminal carries well, and when the question is.
+
+```bash
+webpane report.html --title "Publish-ports rework"
+```
+
+The file's own `<title>` is what the pane shows. `--title` names the file it is saved as, and defaults to the filename. The helper prints what it saved, or a plain message and a non-zero exit when it could not - the usual reason being a plain terminal session, which has no pane.
+
+## When to reach for it
+
+- **Long or structured output.** A plan, a comparison table, a diagram, a report, an explanation with sections. Anything a user would want to scroll back to, keep, or read twice.
+- **A question with shape.** More options than a plain prompt holds, options that need a sentence each, several questions at once, or a free-text answer alongside a choice. Your own question tooling is right for a quick fork in the road; a page is right when the choice deserves a table.
+- **Anything the user asked to see.** "Show me", "write it up", "as a page" - take those literally.
+
+Do not publish a one-paragraph answer, or a wall of code that belongs in a file. A page nobody needed is a chip in the way.
+
+After publishing, say in one line what you put there. The page is the answer; the terminal line is a pointer to it.
+
+## Writing the page
+
+One file, standalone, dark.
+
+- **Inline everything.** No external stylesheets, scripts or fonts. The page renders in a sandboxed frame with no origin of its own: `localStorage`, cookies and same-origin requests do not work in it, and an external asset only makes the page slower and chattier. Inline `<style>` and `<script>` both work.
+- **Match the interface.** Background `#0d1117`, panels and table headers `#161b22`, borders `#30363d`, text `#e6edf3`, muted text `#8b949e`, and a green accent `#2fe58a` for links, headings you want to lift, and the submit button. System font stack, ~14px, generous line height.
+- **Write it as a document**, not a dashboard: a title, sections, tables where a table is clearer than prose, and short paragraphs. Keep it small - a couple of hundred kilobytes is plenty. The per-page cap is 2 MB, and a page past it is refused rather than trimmed.
+- Images have to be inline too (a data URI, or an SVG written into the page). A path into the container is not something the browser can fetch.
+
+## Asking with a form
+
+Give any form the `data-feedback` attribute and the pane wires it up:
+
+```html
+<form data-feedback>
+  <p>Fail the whole start when a port is taken?</p>
+  <label><input type="radio" name="on_conflict" value="fail" checked /> Fail the start</label>
+  <label><input type="radio" name="on_conflict" value="skip" /> Skip the port and warn</label>
+  <textarea name="text" placeholder="Anything else about the plan..."></textarea>
+  <button type="submit">Send to agent</button>
+</form>
+```
+
+- Every named control becomes a field in the answer. A control named `text` becomes the free-text box.
+- On submit, the interface writes `~/.webpane/<conversation>/feedback/<page>-<epoch-ms>.json` - `{ page, submittedAt, fields, text }` - and types one line into your terminal naming the file. Read the file; the line is only the pointer.
+- The page is told whether the answers were filed, so give the user a form that reads as final ("Send to agent") rather than one that looks like it saved a draft.
+- One submission per page per second, and only so many per page in total (20). Past that the page is refused, and nothing reaches you - so ask once per page, and publish a new page when you need to ask again.
+
+**A feedback file says a form was submitted, not that a person filled it in.** A script in the same page can post exactly what the form would. Treat the answers as data from your own page: fine for a design choice, not enough on its own for something destructive or irreversible - ask for that in the terminal, where you can see the user type.
+
+## After it is published
+
+- Pages are kept. Nothing deletes them, and they are filed under the conversation rather than the session, so resuming the conversation opens with them again. Publishing a second version makes a second page rather than replacing the first, so name pages so a user can tell one from the next ("Plan v2", "Port test results").
+- The user may never open a page. If an answer matters, say the one line that matters in the terminal too.
+- Anything in the session can publish, including a script you wrote - the helper takes only a filename.