@muhkoo/cli 0.14.0-alpha.7 → 0.14.0-alpha.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -14,9 +14,8 @@ npm install -g @muhkoo/cli@alpha
14
14
  npx @muhkoo/cli@alpha --help
15
15
  ```
16
16
 
17
- Ask for the **`alpha`** tag explicitly. `latest` still points at the older
18
- `0.13.2-alpha.0` line, so a bare install gets a CLI without the commands
19
- documented here.
17
+ The **`alpha`** and **`latest`** tags both point at the newest alpha, and the
18
+ CLI is released in lockstep with `@muhkoo/connect`.
20
19
 
21
20
  Requires Node.js 20+.
22
21
 
@@ -85,7 +84,9 @@ muhkoo devices rm <factorId> # withdraw access — takes effect immediately
85
84
  Revoking the machine you are on also clears its now-useless local key, so the
86
85
  next filesystem command pairs again from scratch rather than retrying a pairing
87
86
  the server has forgotten. `MUHKOO_SEED` bypasses pairing entirely, for CI, where
88
- there is no interactive login to pair with.
87
+ there is no interactive login to pair with. `--no-pair` signs in for one command
88
+ and stores nothing. (In 0.14.0-alpha.8 the flag was ignored, and the machine
89
+ was paired anyway.)
89
90
 
90
91
  ## Environments
91
92
 
@@ -105,7 +106,9 @@ muhkoo whoami --base https://api.example.com
105
106
  Account login · logout · devices ls|rm · whoami
106
107
  Apps apps ls|get|create|slug|rm · keys rotate · tokens ls|create|revoke
107
108
  Backend provision · tables · agents · functions
108
- Files vfs ls|cat|put|get|rm|cp|mv|find|history|restore · vcs status|commit|log|diff|branch|switch|merge
109
+ Files vfs cd|pwd|ls|stat|tree|cat|put|get|mkdir|rm|cp|mv|find|history|restore
110
+ vfs import|mount|ignore · vfs sweep|use-app|app
111
+ vcs status|commit|log|show|diff|branch|switch|checkout|merge|restore · vcs merge --abort
109
112
  Hosting deploy · promote · hosting status|rollback|rm-release|unpublish · domains
110
113
  Tools logs · eject
111
114
  ```
@@ -125,6 +128,104 @@ muhkoo agents enable <appId> <agentId> --channel general
125
128
  muhkoo eject src/agent/agentApp.ts # preview an agent's prompt + tools
126
129
  ```
127
130
 
131
+ ## Syncing a directory
132
+
133
+ This section describes 0.14.0-alpha.9. In 0.14.0-alpha.8,
134
+ `vfs ignore [dir] [--write]` only drafts a `.vcsignore`, with no `--accept` or
135
+ `--draft`, and `import` runs the full two-way sync: it writes remote files
136
+ into the project, and with `--allow-delete` it deletes local files too.
137
+
138
+ ```bash
139
+ muhkoo vfs import ./my-app --dry-run # what would upload, and what import skips
140
+ muhkoo vfs import ./my-app # upload once, to /apps/<slug>
141
+ muhkoo vfs mount ./my-app --path /apps/my-app --dry-run # what mounting would do
142
+ muhkoo vfs mount ./my-app --path /apps/my-app # two-way sync, live until Ctrl-C
143
+ muhkoo vfs ignore ./my-app # what earlier ignore rules still hold back
144
+ muhkoo vfs ignore ./my-app --accept # preview an accept, and its digest
145
+ muhkoo vfs ignore ./my-app --accept <digest> # accept exactly the files you previewed
146
+ ```
147
+
148
+ `import` uploads whole projects once, then stops. It only uploads: it never
149
+ writes or deletes anything on this disk. Each directory goes to `/apps/<slug>`,
150
+ where `<slug>` comes from its `.muhkoo-app.json`, or failing that its own name.
151
+ If any directory fails, the rest are still tried and the command exits 1.
152
+ `--dry-run` works for both. For `import` it lists what would upload; for `mount`
153
+ it lists what mounting would download, upload and delete, then stops without
154
+ syncing or watching. Neither writes anything, not even for a moment: not in the
155
+ directory, not under `~/.muhkoo`, and not in your filesystem. A dry run does not
156
+ pair this machine either; if it is not paired yet, you sign in for that one
157
+ command. (In 0.14.0-alpha.8, `mount` ignored `--dry-run` and mounted for real.)
158
+
159
+ `mount` keeps one directory in sync with your filesystem until you stop it.
160
+ `--path` defaults to `/`, your whole filesystem, so pass the subtree you mean.
161
+ Ctrl-C, SIGTERM or closing the terminal stops it after the current file and
162
+ saves its state. A second Ctrl-C quits at once (exit code 130), which is safe
163
+ because every file lands by renaming a temp file into place.
164
+
165
+ What syncs is decided by a root `.vcsignore` if there is one. Otherwise git's
166
+ rules apply in full: every `.gitignore`, each scoped to its own directory, and
167
+ `.git/info/exclude`. Built-in Node defaults sit underneath either way (build
168
+ output, logs, `.env` and `.env.*`, but not `.env.example`). Dot-files, other
169
+ than `.vcsignore` and `.gitignore` files, are skipped unless you pass
170
+ `--hidden`. `muhkoo vfs ignore <dir> --draft` prints a `.vcsignore` drafted
171
+ from all of them.
172
+
173
+ ### What mount and import protect against
174
+
175
+ Every app you sign into holds your master seed, so any of them can write your
176
+ filesystem, and so choose the paths, names and bytes that `mount` brings down.
177
+ Everything read from your filesystem is therefore treated as untrusted input,
178
+ and it cannot reach this disk except through these checks:
179
+
180
+ - **Some paths never sync, in either direction.** No flag and no ignore rule
181
+ changes that: `.git`, `.ssh`, `.muhkoo`, `node_modules`, `.husky`, editor and
182
+ agent directories (`.vscode`, `.idea`, `.config`, `.claude`, `.cursor`,
183
+ `.zed`, `.fleet`), and credential and shell start-up files (`.envrc`,
184
+ `.npmrc`, `.netrc`, `.gitconfig`, `.profile`, `.bashrc`, `.zshrc`, `.zshenv`
185
+ and the rest). Each one either holds credentials or can run code without an
186
+ execute bit. Names are compared the way a case-folding volume would compare
187
+ them, so `Node_Modules`, `.GIT` and `GIT~1` are refused too.
188
+ - **Never your home directory.** Both commands refuse the filesystem root, your
189
+ home directory, and anything that contains it. There is no override.
190
+ - **One write boundary.** Every write and delete on disk checks each part of
191
+ the path: no symlinks, no alternative spellings, and no replacing a local
192
+ file that is not synced. A new file never gets an execute bit.
193
+ - **An edit to an ignore file cannot widen what syncs.** A new exclusion
194
+ applies at once. A loosening, whether you made it or it arrived from your
195
+ filesystem, waits until `muhkoo vfs ignore <dir> --accept <digest>` accepts
196
+ exactly the files you previewed. Each change to the rules since the last
197
+ accept is kept as another set, up to 64 sets or 2 MB. Past that, or if the
198
+ stored rules cannot be read, nothing syncs until you accept.
199
+ - **Deletes are off by default, in both directions.** A delete removes the
200
+ file's history too, so unlike an overwrite it cannot be undone.
201
+ `--allow-delete` trusts the remote side. A pass that would delete more than 3
202
+ files and leave fewer than half of those it has tracked, or delete anything
203
+ when the other side is empty, deletes nothing in that direction and says why.
204
+ That guard catches a missing or renamed root, not whatever can write your
205
+ filesystem.
206
+ - **Each pass is bounded.** Files over 100 MB are skipped. One pass of `mount`
207
+ pulls at most 2 GiB or 10,000 files and reads at most as much to compare. A
208
+ pull waits when it would leave less than 5% of the disk free (at least 1 GiB,
209
+ at most 10 GiB). A size your filesystem reports can only get a file skipped
210
+ or held sooner: the size limit, the pull budget and the reserve are checked
211
+ again against the bytes that arrive.
212
+ - **Remote text is escaped** before it reaches your terminal, so a planted
213
+ file name or commit message cannot send control sequences.
214
+
215
+ What this does not cover: ordinary project files, such as source, scripts,
216
+ `bin/` and package-manager configs, still sync in both directions, so an app
217
+ holding your seed can change code that you later run. Anything you upload can
218
+ be read by every app you sign into. The root cause, apps being handed your
219
+ master seed at sign-in, is not fixed yet.
220
+
221
+ If you used `--hidden` with 0.14.0-alpha.8 or earlier, it may have uploaded
222
+ `.git/`, `.npmrc`, `.netrc` and similar files, and `.env` files if an ignore
223
+ file negated the default `.env` rules. Check with `muhkoo vfs tree`, remove
224
+ them with `muhkoo vfs rm -r`, and rotate any token they held. Before the first
225
+ run, also look over your ignore files, nested ones included, for lines you did
226
+ not write: this version takes whatever is on disk the first time it runs as
227
+ your own rules. The [CHANGELOG](./CHANGELOG.md) has the details.
228
+
128
229
  ## The provision spec
129
230
 
130
231
  ```jsonc
package/bin/muhkoo.js CHANGED
@@ -8,10 +8,17 @@
8
8
  */
9
9
 
10
10
  import { run } from "../src/index.js";
11
+ import { printable } from "../src/lib/ui.js";
11
12
 
12
13
  run(process.argv.slice(2))
13
14
  .then(() => process.exit(0))
14
15
  .catch((e) => {
15
- console.error(`\n✗ ${e?.stack || e?.message || String(e)}\n`);
16
+ // Escaped like everything else printed: an error's message can carry a
17
+ // name or a server's words. The message is one line; the stack's frames
18
+ // are Node's own lines.
19
+ const head = e instanceof Error ? `${e.name}: ${e.message}` : String(e);
20
+ const stack = e instanceof Error && typeof e.stack === "string" ? e.stack : "";
21
+ const frames = stack.startsWith(head) ? stack.slice(head.length).split("\n").filter(Boolean) : [];
22
+ console.error(["", `✗ ${printable(head)}`, ...frames.map(printable), ""].join("\n"));
16
23
  process.exit(1);
17
24
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@muhkoo/cli",
3
- "version": "0.14.0-alpha.7",
3
+ "version": "0.14.0-alpha.9",
4
4
  "description": "Command-line interface for the Muhkoo platform — provision backends, deploy apps, and manage agents, functions, databases, and domains.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -40,7 +40,7 @@
40
40
  "release": "npm publish --tag alpha && npm dist-tag add @muhkoo/cli@$npm_package_version latest"
41
41
  },
42
42
  "dependencies": {
43
- "@muhkoo/connect": "0.14.0-alpha.7",
43
+ "@muhkoo/connect": "0.14.0-alpha.9",
44
44
  "snarkjs": "^0.7.0"
45
45
  },
46
46
  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e",
@@ -55,7 +55,7 @@ async function add(ctx, appId, args) {
55
55
  ok(`Attached ${c.bold(hostname)}.`);
56
56
  const records = r.body?.records || r.body?.dnsRecords || [];
57
57
  if (records.length) {
58
- info("\nAdd these DNS records at your registrar:");
58
+ info("", "Add these DNS records at your registrar:");
59
59
  table(
60
60
  ["TYPE", "NAME", "VALUE"],
61
61
  records.map((d) => [d.type, d.name, d.value]),
@@ -7,7 +7,7 @@ import { readFile } from "node:fs/promises";
7
7
  import { devContext } from "../lib/config.js";
8
8
  import { devCall, ensure } from "../lib/http.js";
9
9
  import { resolveSpace } from "../lib/spaces.js";
10
- import { table, json, ok, info, die } from "../lib/ui.js";
10
+ import { table, json, ok, info, die, writeText } from "../lib/ui.js";
11
11
 
12
12
  export const help = `muhkoo functions — manage serverless functions
13
13
 
@@ -70,7 +70,7 @@ async function code(ctx, appId, args) {
70
70
  const id = args._[3];
71
71
  if (!id) die("Usage: muhkoo functions code <appId> <functionId>");
72
72
  const r = ensure(await devCall(ctx, "GET", `/api/apps/${appId}/functions/${id}/code`), "Read function code");
73
- process.stdout.write((r.body?.code ?? "") + "\n");
73
+ writeText((r.body?.code ?? "") + "\n");
74
74
  }
75
75
 
76
76
  async function deployOne(ctx, appId, args) {
@@ -57,7 +57,8 @@ export default async function login(args) {
57
57
  ok(`Signed in${username ? ` as ${c.bold(username)}` : ""} → ${baseUrl}`);
58
58
  if (me.ok && me.body?.needsBootstrap) {
59
59
  info(
60
- `\n${c.yellow("Note:")} your developer account isn't set up yet. Run ` +
60
+ "",
61
+ `${c.yellow("Note:")} your developer account isn't set up yet. Run ` +
61
62
  `\`muhkoo apps create --slug <name> --email you@example.com\` to bootstrap it.`,
62
63
  );
63
64
  } else if (me.ok && me.body?.tier) {
@@ -16,7 +16,7 @@ import { readFile, access } from "node:fs/promises";
16
16
  import { loadConfig, resolveBase, resolveToken } from "../lib/config.js";
17
17
  import { devCall, ensure } from "../lib/http.js";
18
18
  import { firstOf } from "../lib/args.js";
19
- import { step, ok, info, die, c } from "../lib/ui.js";
19
+ import { step, ok, info, die, c, json } from "../lib/ui.js";
20
20
 
21
21
  export const help = `muhkoo promote — promote an app's TEST hosting to PRODUCTION
22
22
 
@@ -55,7 +55,7 @@ export default async function promote(args) {
55
55
 
56
56
  if (args.json) {
57
57
  info("");
58
- console.log(JSON.stringify(r.body, null, 2));
58
+ json(r.body);
59
59
  } else {
60
60
  info("");
61
61
  ok("Promoted test → production.");
@@ -53,7 +53,7 @@ export default async function provision(args) {
53
53
  const spec = await readJson(args.spec);
54
54
  const prior = (await fileExists(OUT)) ? await readJson(OUT) : null;
55
55
  const ctx = await devContext(args);
56
- info(`API base: ${ctx.baseUrl}${DRY ? " (dry run)" : ""}\n`);
56
+ info(`API base: ${ctx.baseUrl}${DRY ? " (dry run)" : ""}`, "");
57
57
 
58
58
  if (args.enable) {
59
59
  if (!prior?.appId) die(`--enable needs a prior ${OUT} from a provisioning run.`);
@@ -91,7 +91,7 @@ export default async function provision(args) {
91
91
  info(` tables: ${tables.join(", ") || "(none)"}`);
92
92
  info(` hosting: ${hostingUrl} (run \`muhkoo deploy\` once your client is built)`);
93
93
  if ((agents || []).some((a) => a.enableChannel) || (functions || []).some((f) => f.enableChannel)) {
94
- info("\nNext: run the app once so its channels exist, then:");
94
+ info("", "Next: run the app once so its channels exist, then:");
95
95
  info(` muhkoo provision --spec ${args.spec} --enable`);
96
96
  }
97
97
  }
@@ -96,7 +96,7 @@ async function create(ctx, appId, args) {
96
96
  ok(`Created ${t.env} access token${t.label ? ` ${c.bold(t.label)}` : ""} (${t.keyId})`);
97
97
  info(` scopes: ${(t.scopes || scopes).join(", ")}`);
98
98
  if (t.expiresAt) info(` expires: ${fmtDate(t.expiresAt)}`);
99
- info(`\n ${c.bold(t.plaintext)}`);
99
+ info("", ` ${c.bold(t.plaintext)}`);
100
100
  warn("Save this token now — it is shown only once.");
101
101
  }
102
102
 
@@ -27,6 +27,9 @@ Usage:
27
27
  muhkoo vcs switch <name> move onto a branch
28
28
  muhkoo vcs checkout <commit> inspect an old state (detaches HEAD)
29
29
  muhkoo vcs merge <name> bring a branch into this one
30
+ muhkoo vcs merge --abort give up on a merge that stopped for
31
+ conflicts, or whose record cannot be
32
+ read (--discard: put the files back too)
30
33
  muhkoo vcs restore <path> [<commit>] put one file back
31
34
 
32
35
  Options:
@@ -60,12 +63,23 @@ export default async function vcs(args) {
60
63
  switch (sub) {
61
64
  case "status": {
62
65
  const changes = await repo.status();
63
- const branch = (await repo.currentBranch()) ?? `${c.dim("detached at")} ${short(await repo.current())}`;
64
- const pending = await repo.pendingMerge();
65
- if (args.json) return json({ project: slug, branch, changes, merging: pending?.name ?? null });
66
+ const name = await repo.currentBranch();
67
+ const detached = name ? null : short(await repo.current());
68
+ // Status is what people run to find out what is wrong, so a merge record
69
+ // that cannot be read is said, with the way out, not thrown.
70
+ const { pending, unreadable } = await readPending(repo);
71
+ if (args.json) {
72
+ return json({
73
+ project: slug, branch: name ?? `detached at ${detached}`, changes, merging: pending?.name ?? null,
74
+ ...(unreadable ? { mergeUnreadable: true } : {}),
75
+ });
76
+ }
66
77
 
67
- info(`${c.bold(slug)} on ${branch}`);
78
+ info(`${c.bold(slug)} on ${name ?? `${c.dim("detached at")} ${detached}`}`);
68
79
  if (pending) warn(`Merging ${pending.name} — resolve the files below, then commit to finish it.`);
80
+ if (unreadable) {
81
+ warn("A merge is in progress, but its record cannot be read, so no commit can be made until it is cleared: `muhkoo vcs merge --abort`.");
82
+ }
69
83
  if (!changes.length) return info("Nothing has changed since the last commit.");
70
84
  return table(["", "PATH"], changes.map((ch) => [mark(ch.kind), ch.path]));
71
85
  }
@@ -73,7 +87,7 @@ export default async function vcs(args) {
73
87
  case "commit": {
74
88
  if (!message) return die("A commit needs a message: `muhkoo vcs commit -m \"what changed\"`");
75
89
  const hash = await repo.commit(String(message));
76
- return ok(`${short(hash)} ${message}`);
90
+ return ok(`${short(hash)} ${subject(message)}`);
77
91
  }
78
92
 
79
93
  case "log": {
@@ -85,7 +99,7 @@ export default async function vcs(args) {
85
99
  entries.map((e) => [
86
100
  short(e.hash) + (e.parents.length > 1 ? c.dim(" (merge)") : ""),
87
101
  when(e.at),
88
- e.message,
102
+ subject(e.message),
89
103
  ]),
90
104
  );
91
105
  }
@@ -148,6 +162,49 @@ export default async function vcs(args) {
148
162
  }
149
163
 
150
164
  case "merge": {
165
+ // The way out of a merge. Without it a CLI-only user was told to abort a
166
+ // merge with no command that does, and a pending-merge record that could
167
+ // not be read stopped every `vcs commit` for good.
168
+ if (args.abort) {
169
+ // `merge --abort feature` parses as abort: "feature", `merge --abort
170
+ // -m x` as abort: "-m" with x left over, and `--discard feature` as
171
+ // discard: "feature". Refuse whatever came with it, rather than guess
172
+ // what was meant.
173
+ const extra = [
174
+ ...["abort", "discard", "json"].filter((k) => typeof args[k] === "string").map((k) => args[k]),
175
+ ...args._.slice(2),
176
+ ...(message !== undefined ? ["-m", message] : []),
177
+ ...(count !== undefined ? ["-n", count] : []),
178
+ ];
179
+ if (extra.length) {
180
+ return die(
181
+ `\`vcs merge --abort\` takes nothing else, but was given: ${extra.join(" ")}`,
182
+ " Run it on its own to give up on the merge, with --discard to put your files back too.",
183
+ );
184
+ }
185
+ const { pending, unreadable } = await readPending(repo);
186
+ if (!pending && !unreadable) return args.json ? json({ aborted: false, merge: null }) : info("No merge in progress.");
187
+ await repo.abortMerge();
188
+ const merged = pending?.name ?? null;
189
+ // Back as they were before the merge: the branch's tip — or, on a
190
+ // detached HEAD, the commit it is at, since switching to a branch would
191
+ // move HEAD somewhere else. HEAD that cannot be read has neither.
192
+ const branch = await repo.currentBranch().catch(() => null);
193
+ const head = branch ? null : await repo.current().catch(() => null);
194
+ const back = branch
195
+ ? { command: `muhkoo vcs switch ${branch} --discard`, run: () => repo.switchTo(branch, { discardChanges: true }) }
196
+ : head
197
+ ? { command: `muhkoo vcs checkout ${short(head)} --discard`, run: () => repo.checkout(head, { discardChanges: true }) }
198
+ : null;
199
+ if (args.discard && back) await back.run();
200
+ if (args.json) return json({ aborted: true, merge: merged });
201
+ return ok(
202
+ `Abandoned the merge${merged ? ` of ${merged}` : ""}. The next commit is an ordinary one.`,
203
+ args.discard && back
204
+ ? " Your files are back as they were before the merge."
205
+ : ` Your files are as the merge left them; \`${back?.command ?? "muhkoo vcs switch <branch> --discard"}\` puts them back.`,
206
+ );
207
+ }
151
208
  const name = required(a(2), "merge <name>");
152
209
  const result = await repo.merge(name, { discardChanges: Boolean(args.discard) });
153
210
  if (result.kind === "up-to-date") return info(`Already up to date with ${name}.`);
@@ -210,6 +267,23 @@ async function parentOf(repo, hash) {
210
267
  }
211
268
  }
212
269
 
270
+ /**
271
+ * The merge in progress, or null — with `unreadable` when connect cannot read
272
+ * its record, the case `merge --abort` exists for. Only that error is caught:
273
+ * a network failure, or no session, says nothing about the record, and
274
+ * clearing it on one would report a merge abandoned that may never have been.
275
+ */
276
+ async function readPending(repo) {
277
+ try {
278
+ return { pending: await repo.pendingMerge(), unreadable: false };
279
+ } catch (err) {
280
+ if (err?.name === "VcsError" && /^the merge in progress cannot be read\b/.test(String(err.message))) {
281
+ return { pending: null, unreadable: true };
282
+ }
283
+ throw err;
284
+ }
285
+ }
286
+
213
287
  function required(value, usage) {
214
288
  if (value === undefined) die(`Usage: muhkoo vcs ${usage}`);
215
289
  return value;
@@ -220,6 +294,15 @@ function short(hash) {
220
294
  return hash ? String(hash).slice(0, 8) : "-";
221
295
  }
222
296
 
297
+ /**
298
+ * A commit message's first line, as `git log --oneline` shows it. Every
299
+ * newline in a table cell is printed as a visible escape, so a body read as
300
+ * `fix\u000a\u000alonger body`; the whole message is in `vcs log --json`.
301
+ */
302
+ function subject(message) {
303
+ return String(message ?? "").split(/\r?\n/)[0];
304
+ }
305
+
223
306
  function mark(kind) {
224
307
  return kind === "added" ? c.dim("+") : kind === "removed" ? c.dim("-") : c.dim("~");
225
308
  }