moshcode 0.38.0 → 0.40.0

package/README.md

@@ -43,6 +43,8 @@ or miss one that does. A test fails the build when it drifts.
 | `moshcode login` | account | authenticate with app.moshcode.sh |
 | `moshcode whoami` | account | show the logged-in account |
 | `moshcode logout` | account | clear the logged-in account |
+| `moshcode save` | account | save this machine's pit settings to your account |
+| `moshcode load` | account | bring your saved pit settings onto this machine |
 | `moshcode console` | account | serve or connect to the browser terminal |
 | `moshcode dns` | hosting | resolve Moshpit names on this machine |
 | `moshcode doh` | hosting | run the DNS-over-HTTPS resolver |
@@ -543,6 +545,24 @@ an equity's score, and each response ships the `caveats` that say so. Prices are
 Alpaca's US venue alone and can differ materially from other exchanges. Research
 aid, not advice — and like `stocks`, nothing under `crypto` can place an order.
 
+### Aliases (`/alias`)
+
+The pit is a prompt you sit at all day, so it lets you name the lines you keep
+retyping. An alias runs in `$SHELL` unless it starts with `/`, in which case it
+is a pit command:
+
+```text
+/alias set gs "git status"        # then /gs — and /gs -sb appends to it
+/alias set cx "/agents codex"     # a pit command, not a shell one
+/alias                            # what is defined
+/alias rm gs
+```
+
+They live in `~/.moshcode/aliases.json` (owner-only, like the history file) and
+survive between sessions. A name that is already a pit command, an engine, or a
+tool is refused rather than shadowed — built-ins are dispatched first, so such
+an alias would never run.
+
 ### Social posting from the pit
 
 The pit can hand a prepared post to Bluesky or Nostr without storing either
@@ -561,6 +581,52 @@ event, and publishes it to the displayed relays. Both flows leave the final
 confirmation in the browser. If the pit is remote or headless, `/post` prints
 the composer URL instead.
 
+## Settings sync (`/save` and `/load`)
+
+Your pit becomes yours by accretion — a dozen aliases, herd rules you tuned until
+the roster stopped lying to you. All of it lives in `~/.moshcode` on one machine,
+which is why every new laptop, container and droplet used to feel like someone
+else's prompt.
+
+`/save` pushes that configuration to your `app.moshcode.sh` account. `/load`
+brings it down onto any machine you have run `/login` on.
+
+```sh
+moshcode save                 # push this machine's settings (pit: /save)
+moshcode save --dry-run       # what would go up, and stop
+
+# on the new box
+moshcode login
+moshcode load                 # pull them down (pit: /load)
+moshcode load --dry-run       # the per-file plan, changing nothing
+```
+
+What syncs is an allowlist, not a directory walk:
+
+| file | what it is |
+|---|---|
+| `~/.moshcode/aliases.json` | your pit aliases (`/alias`) |
+| `~/.moshcode/herd/rules.json` | herd state-detection overrides |
+
+What never syncs, by name: `credentials.json` (the account token this very
+feature authenticates with), `herd/sessions.json` (live state pinned to one tmux
+server), `sync.json`, and the `pkg/` binary cache. Engine configuration
+(`~/.claude.json` and friends) is deliberately left alone — those files carry
+provider API keys.
+
+Nothing is overwritten quietly:
+
+- Each save is a numbered **revision**. `/save` sends the revision it last agreed
+  on, and the app refuses the write if another machine has saved since — you get
+  told, with `/load` and `/save --force` as the two ways out.
+- `/load` refuses to replace a settings file you edited since this machine last
+  synced, and names it. `--force` overrides.
+- The last ten revisions are kept. See them, and which machine each came from, at
+  [app.moshcode.sh/settings/sync](https://app.moshcode.sh/settings/sync) — where
+  you can also promote an older revision or delete the lot.
+
+Both verbs take `--json`, so a provisioning script can act on the result.
+
 ## Browser terminal (`moshcode console`)
 
 A real terminal in the browser — arrow keys, history, full-screen TUIs — because

package/bin/moshcode.mjs

@@ -26,6 +26,7 @@ import { canOpenBrowser, openBrowser } from "../src/open-url.mjs";
 import { locate, tilde } from "../src/pwd.mjs";
 import { createPrd, listPrds, authoringPrompt } from "../src/prd.mjs";
 import { loginAuto, whoami, logout } from "../src/auth.mjs";
+import { loadCommand, saveCommand } from "../src/settings-sync.mjs";
 import { tui } from "../src/tui.mjs";
 import { consoleCommand } from "../src/console.mjs";
 import { herdCommand, herdStart, splitDetachArgs } from "../src/herd-cli.mjs";
@@ -609,6 +610,8 @@ async function main() {
     return;
   }
   if (cmd === "logout") { logout(); return; }
+  if (cmd === "save") { process.exitCode = await saveCommand(rest); return; }
+  if (cmd === "load") { process.exitCode = await loadCommand(rest); return; }
   if (cmd === "run") {
     let max = 3, dryRun = false;
     let optionsEnded = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moshcode",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "type": "module",
   "description": "moshcode — a metal wrapper for coding engines and native UGig/CoinPay workflow CLIs, with OpenPRD and moshscript",
   "repository": {

package/prd/0010-cloud-settings-sync.md

@@ -0,0 +1,132 @@
+---
+openprd: "0.2"
+id: "0010"
+title: "Sync the pit's settings to your moshcode.sh account"
+status: Draft
+authors:
+  - anthony@profullstack.com
+created: 2026-08-11
+updated: 2026-08-11
+repo: https://github.com/moshcoder/moshcode
+discussion:
+implementation: src/settings-sync.mjs · apps/pwa/src/routes/settings-sync.mjs
+tags: account, settings, sync
+supersedes:
+superseded-by:
+---
+
+## Problem
+
+A pit becomes yours by accretion. You add `/alias set gs "git status"`, then a
+dozen more; you tune the herd's rules until it stops calling a working agent
+blocked. None of it is in a repo, none of it is in a dotfile anyone syncs, and
+all of it lives in `~/.moshcode` on exactly one machine.
+
+So the second machine is a stranger. A new laptop, a fresh container, a droplet
+you SSH into to babysit an agent, a reinstall after a disk swap — each one starts
+from nothing, and the muscle memory built at the first prompt does not work at
+the second. People already log in to `app.moshcode.sh` (`/login`) for approvals,
+notifications and the session mirror, so the account that could hold this
+configuration is already there and already paired with every machine.
+
+## Goals
+
+- Moving to a new machine costs `/login` and `/load`, not an afternoon of
+  remembering what you had.
+- A person can see what is stored on their account, and delete it, from the web.
+- Nobody is ever surprised by a settings overwrite — not from another machine,
+  and not over their own uncommitted edits.
+- No credential, key or token is ever part of what syncs, and that fact is
+  enforced by a test rather than by care.
+
+## Non-Goals
+
+- Continuous or background sync. Settings are edited by a person at a moment they
+  can name; a daemon that pushes silently is a daemon that overwrites silently.
+- Syncing engine configuration (`~/.claude.json`, `~/.codex`, MCP registrations).
+  Those files carry provider API keys and are owned by other tools' schemas.
+- Syncing machine state: live herd sessions, the package cache, shell history.
+  None of it means anything on a different box.
+- Merging. Two divergent settings files are resolved by a person choosing one,
+  not by a three-way merge of someone's aliases.
+
+## Users
+
+- **The multi-machine moshcoder** — laptop, desktop, a dev box, and a container
+  per project. Wants the same prompt everywhere.
+- **The reinstaller** — new OS, same person. Wants their aliases back.
+- **The team lead** — one account, several machines, and a strong preference for
+  never explaining to a colleague why their aliases disappeared.
+
+## Requirements
+
+- R1 [P0] `/save` (and `moshcode save`) uploads this machine's pit settings to the
+  logged-in account. `/load` (`moshcode load`) brings them back down.
+- R2 [P0] What syncs is an allowlist, not a directory walk: `aliases.json` and
+  `herd/rules.json` today. `credentials.json`, `herd/sessions.json`, `sync.json`
+  and `pkg/` are named as never-synced and asserted in tests.
+- R3 [P0] Each save is a numbered revision. `/save` sends the revision it last
+  agreed on and the app refuses the write if the account has moved past it, so
+  two machines cannot silently erase one another.
+- R4 [P0] `/load` refuses to overwrite a settings file that changed locally since
+  the last sync, and names the file. `--force` overrides; `--dry-run` shows the
+  per-file plan and writes nothing.
+- R5 [P0] Every path in a downloaded snapshot is re-checked against the allowlist
+  before anything is written. A snapshot is data from the network, and an
+  unchecked path in it makes `/load` a remote write primitive.
+- R6 [P1] The app keeps the last ten revisions, shows them at
+  `/settings/sync` with the machine and time each came from, and can promote an
+  older one to current.
+- R7 [P1] `--json` on both verbs, so a provisioning script can act on the result.
+- R8 [P1] A snapshot records which engines and tools the source machine had
+  installed. `/load` names the missing ones as a suggestion; it never installs.
+- R9 [P2] Not logged in, session expired, nothing saved yet, conflict: each is a
+  sentence naming the command that resolves it (`/login`, `/save`, `/load`,
+  `--force`).
+
+## UX Notes
+
+```
+mosh ▸ /save
+  ✓ saved 2 files to you@example.com (revision 3)
+     aliases.json  pit aliases
+     herd/rules.json  herd state rules
+     on another machine: `/login` then `/load`
+
+mosh ▸ /load                       # on the new box
+  loaded revision 3 from dev — 2 files written
+     added    aliases.json
+     added    herd/rules.json
+     that machine also had codex, gh — `/install <name>` to match it
+
+mosh ▸ /load                       # after editing aliases locally
+  1 local file changed since this machine last synced:
+     aliases.json
+     `/save` to keep them, `/load --force` to replace them, `/load --dry-run` to see the difference
+```
+
+The pit never blocks on this: both verbs are one request and some printing, so
+readline keeps the prompt. `~/.moshcode/sync.json` remembers the revision and a
+per-file digest — that digest is what separates "someone else saved" from "you
+edited this five minutes ago", which want opposite answers.
+
+## Success Metrics
+
+- A fresh machine reaches a familiar prompt in two commands (`/login`, `/load`).
+- Zero settings-loss reports: every destructive path is either refused or
+  recoverable from `/settings/sync`.
+- No credential ever appears in a stored snapshot (asserted, not audited).
+
+## Risks & Open Questions
+
+- **Scope creep into secrets.** The most-requested next file will be an engine
+  config that holds an API key. Holding the line — settings, never credentials —
+  is what keeps `/load` safe to run on a machine you share.
+- **Ten revisions is a guess.** Cheap to raise; it exists so a bad `/save` from
+  the wrong machine is recoverable at all.
+- **A snapshot version bump.** Handled by refusing to read a newer snapshot and
+  naming `moshcode upgrade`, rather than by guessing at a shape this build has
+  never seen.
+- **Should `/load` be able to pick a revision?** The app stores ten and the web
+  page can promote one, which covers recovery without adding a flag that takes a
+  number. Open if people ask for `--revision`.

package/prd/README.md

@@ -25,4 +25,5 @@ Start one with `moshcode prd "<idea>"` (TUI: `/prd`).
 | [0007](0007-profullstack-site-init.md) | Generate batteries-included Profullstack sites for Moshpit names | Draft |
 | [0008](0008-ticker-research-and-plugin-marketplace.md) | Bring equity research into the pit, and ship the pit's slash commands as a plugin | Draft |
 | [0009](0009-persistent-agent-runtime.md) | Keep the herd alive — a persistent runtime, semantic agent state, and one control surface for humans and agents | Accepted |
+| [0010](0010-cloud-settings-sync.md) | Sync the pit's settings to your moshcode.sh account | Draft |
 <!-- PRD-INDEX:END -->

package/src/aliases.mjs

@@ -0,0 +1,160 @@
+// Named shortcuts for whatever you type at the mosh prompt.
+//
+// The pit is a prompt people sit at all day, and the things they retype are
+// their own: `git status`, `pnpm -r test`, `/agents claude --resume`. Shell
+// aliases can't help — the pit is not a shell, and `!git status` is exactly the
+// keystrokes an alias is supposed to save. So the pit keeps its own.
+//
+// An alias is a name and a line. The line is a shell command unless it starts
+// with `/`, in which case it is a pit command:
+//
+//   /alias set gs "git status"       → /gs   runs `$SHELL -c "git status"`
+//   /alias set cc "/agents claude"   → /cc   opens claude autonomously
+//
+// Shell-by-default because that is what the prompt is mostly asked for, and the
+// leading slash is already how the pit spells its own verbs — so the rule reads
+// the same way the rest of the pit does rather than being a new convention.
+//
+// Anything the pit can dispatch is fair game as a value, which is what keeps
+// this from needing to grow a type: a bookmarklet or a URL becomes an alias the
+// day the pit gets a verb that opens one, with no change here.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Owner-only, and for the same reason ~/.moshcode_history is: values are
+ * whatever was typed, and people alias commands that carry tokens. */
+const FILE_MODE = 0o600;
+
+const NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+
+/** A value long enough to be a pasted mistake rather than a command. */
+const MAX_VALUE = 4096;
+
+/**
+ * How many times one line may expand before the pit gives up.
+ *
+ * Aliases can name aliases (`/alias set st "/gs --short"`), which is useful and
+ * also the one way to write a loop: two aliases naming each other would spin
+ * the dispatch loop forever. Ten is far past any chain a person builds on
+ * purpose.
+ */
+export const MAX_EXPANSIONS = 10;
+
+/** Where the aliases live. Derived per call so tests can move $HOME. */
+export function aliasFile() {
+  return path.join(os.homedir(), ".moshcode", "aliases.json");
+}
+
+/**
+ * Every alias, as a plain name → line map.
+ *
+ * A file that is missing, unreadable, or not the shape we wrote reads as "no
+ * aliases" rather than throwing: this is called on the dispatch path for every
+ * unrecognised command, and a hand-edited file with a stray comma must not take
+ * the prompt down with it. Entries whose value is not a string are dropped for
+ * the same reason.
+ */
+export function loadAliases() {
+  let raw;
+  try { raw = fs.readFileSync(aliasFile(), "utf8"); }
+  catch { return {}; }
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch { return {}; }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+  const out = {};
+  for (const [name, value] of Object.entries(parsed)) {
+    if (typeof value === "string" && value.trim()) out[name.toLowerCase()] = value;
+  }
+  return out;
+}
+
+/** Write the map back, creating ~/.moshcode if this is the first alias. */
+function saveAliases(aliases) {
+  const file = aliasFile();
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  // Sorted so the file reads like a list rather than like insertion order, and
+  // so hand edits produce a small diff.
+  const ordered = Object.fromEntries(Object.keys(aliases).sort().map((k) => [k, aliases[k]]));
+  fs.writeFileSync(file, `${JSON.stringify(ordered, null, 2)}\n`, { mode: FILE_MODE });
+  // `mode` only applies at creation, so an existing file keeps whatever the
+  // umask gave it. Tighten every write, the way the history file does.
+  try { fs.chmodSync(file, FILE_MODE); } catch { /* best effort */ }
+}
+
+/** The name as it is stored, or "" for anything that cannot be one. */
+export function normalizeName(name) {
+  const clean = String(name ?? "").trim().toLowerCase().replace(/^\//, "");
+  return NAME_RE.test(clean) ? clean : "";
+}
+
+/** One alias's line, or null. */
+export function getAlias(name) {
+  const key = normalizeName(name);
+  if (!key) return null;
+  const aliases = loadAliases();
+  return Object.hasOwn(aliases, key) ? aliases[key] : null;
+}
+
+/**
+ * Define an alias. Returns { ok, error, name, value, previous }.
+ *
+ * `isReserved` asks the pit whether a name is already its own — a command, an
+ * engine, a tool. A predicate rather than a list because the dispatcher decides
+ * that by resolving, aliases included, and a list copied out of the rosters
+ * here would be a second answer that drifts from the first. A colliding name is
+ * refused rather than shadowed: built-ins are checked first, so an alias named
+ * `agents` would be silently dead, and a shortcut that does nothing is worse
+ * than one that was never accepted.
+ */
+export function setAlias(name, value, { isReserved = () => false } = {}) {
+  const key = normalizeName(name);
+  if (!key) {
+    return { ok: false, error: `"${name}" isn't a usable alias name — letters, digits, . _ - and it must start with a letter or digit` };
+  }
+  if (isReserved(key)) {
+    return { ok: false, error: `/${key} is already a pit command, engine, or tool — pick another name` };
+  }
+  const line = String(value ?? "").trim();
+  if (!line) return { ok: false, error: "an alias needs something to run" };
+  if (line.includes("\n")) return { ok: false, error: "an alias is a single line" };
+  if (line.length > MAX_VALUE) return { ok: false, error: `that value is ${line.length} characters — the cap is ${MAX_VALUE}` };
+
+  const aliases = loadAliases();
+  const previous = Object.hasOwn(aliases, key) ? aliases[key] : null;
+  aliases[key] = line;
+  try { saveAliases(aliases); }
+  catch (e) { return { ok: false, error: `can't write ${aliasFile()}: ${e.message}` }; }
+  return { ok: true, name: key, value: line, previous };
+}
+
+/** Forget one. Returns { ok, error, name, value }. */
+export function removeAlias(name) {
+  const key = normalizeName(name);
+  const aliases = loadAliases();
+  if (!key || !Object.hasOwn(aliases, key)) {
+    return { ok: false, error: `no alias named "${String(name ?? "").replace(/^\//, "")}"` };
+  }
+  const value = aliases[key];
+  delete aliases[key];
+  try { saveAliases(aliases); }
+  catch (e) { return { ok: false, error: `can't write ${aliasFile()}: ${e.message}` }; }
+  return { ok: true, name: key, value };
+}
+
+/**
+ * The line an alias becomes, with anything else the user typed appended.
+ *
+ * Appended rather than substituted, the way a shell alias behaves: `/gs -sb` is
+ * `git status -sb`. `args` is the raw remainder of the typed line, not the
+ * tokenized parts, so the user's own quoting survives into `$SHELL -c`.
+ *
+ * The `!` is what routes a bare value to the shell — the pit already reads a
+ * leading `!` as "run this in $SHELL", so an alias does not need a second path
+ * through it.
+ */
+export function expandAlias(value, args = "") {
+  const line = `${String(value).trim()}${args ? ` ${args}` : ""}`;
+  return /^[/!]/.test(line) ? line : `!${line}`;
+}

package/src/cli-schema.mjs

@@ -278,6 +278,43 @@ export const CORE_CLI_COMMANDS = [
     synopsis: [["moshcode logout", ""]],
     seeAlso: ["login"],
   },
+  {
+    name: "save",
+    group: "account",
+    description: "save this machine's pit settings to your account",
+    synopsis: [["moshcode save [--dry-run] [--force] [--json]", ""]],
+    flags: [
+      ["--dry-run", "list what would be saved and stop", ""],
+      ["--force", "save even if another machine saved after this one last synced", ""],
+      ["--json", "machine-readable result", ""],
+    ],
+    examples: [
+      ["moshcode save", "push aliases + herd rules to app.moshcode.sh"],
+      ["moshcode save --dry-run", "what would go up"],
+    ],
+    seeAlso: ["load", "login", "alias"],
+    note: "aliases (~/.moshcode/aliases.json) and herd rules (~/.moshcode/herd/rules.json). "
+      + "credentials, live herd state and the package cache are never included. "
+      + "each save is a numbered revision; the last ten are kept at app.moshcode.sh/settings/sync.",
+  },
+  {
+    name: "load",
+    group: "account",
+    description: "bring your saved pit settings onto this machine",
+    synopsis: [["moshcode load [--dry-run] [--force] [--json]", ""]],
+    flags: [
+      ["--dry-run", "show the per-file plan and change nothing", ""],
+      ["--force", "overwrite local settings that changed since the last sync", ""],
+      ["--json", "machine-readable result", ""],
+    ],
+    examples: [
+      ["moshcode load", "on a new machine, right after moshcode login"],
+      ["moshcode load --dry-run", "which files would change"],
+    ],
+    seeAlso: ["save", "login", "alias"],
+    note: "refuses rather than overwriting a local file you edited since the last sync — "
+      + "`moshcode save` to keep it, or --force to replace it.",
+  },
   {
     name: "console",
     group: "account",
@@ -891,10 +928,32 @@ export const PIT_COMMANDS = [
   { name: "whoami", cli: "whoami", description: "who this machine is logged in as" },
   // Dispatched since forever and missing from /help until now.
   { name: "logout", cli: "logout", description: "clear the logged-in account" },
+  { name: "save", args: "[--dry-run] [--force]", cli: "save",
+    description: "save this pit's settings to your moshcode.sh account" },
+  { name: "load", args: "[--dry-run] [--force]", cli: "load",
+    description: "bring your saved settings onto this machine" },
   { name: "pwd", aliases: ["where"], cli: "pwd",
     description: "show the current dir + git repo/branch/origin" },
   { name: "shell", aliases: ["sh"], args: "[cmd]", pitOnly: true,
     description: "drop into $SHELL (exit → back to the pit); also !cmd" },
+  { name: "alias", aliases: ["aliases"], args: 'set <name> "<cmd>" | list | get | rm', pitOnly: true,
+    description: "name a line you keep retyping; /<name> runs it",
+    synopsis: [
+      ['/alias set <name> "<command>"', "define one (also: /alias <name> \"<command>\")"],
+      ["/alias [list] [--json]", "every alias"],
+      ["/alias get <name>", "what one expands to"],
+      ["/alias rm <name>", "forget one"],
+    ],
+    examples: [
+      ['/alias set gs "git status"', "then /gs — and /gs -sb appends"],
+      // Deliberately not `cc`: that one is already how the pit spells claude,
+      // so the example would print a refusal for anyone who typed it.
+      ['/alias set cx "/agents codex"', "a pit command, not a shell one"],
+      ["/alias rm gs", ""],
+    ],
+    note: "the command runs in $SHELL unless it starts with / — then it is a pit command. "
+      + "Aliases live in ~/.moshcode/aliases.json and cannot shadow a pit command, engine, or tool.",
+  },
   { name: "help", aliases: ["?", "h"], args: "[command]", pitOnly: true,
     description: "this, or one command in detail" },
   { name: "quit", aliases: ["exit", "q"], pitOnly: true,