@muhkoo/cli 0.15.0-alpha.11 → 0.15.0-alpha.13

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
@@ -105,7 +105,7 @@ muhkoo whoami --base https://api.example.com
105
105
  ```
106
106
  Account login · logout · devices ls|rm · whoami
107
107
  Apps apps ls|get|create|slug|rm · keys rotate · tokens ls|create|revoke
108
- Backend provision · tables · agents · functions
108
+ Backend provision · tables · agents · functions · vectors ls|get|create|rm|notices|query
109
109
  Files vfs cd|pwd|ls|stat|tree|cat|put|get|mkdir|rm|cp|mv|find|history|restore
110
110
  vfs import|mount|ignore · vfs sweep|use-app|app
111
111
  vcs status|commit|log|show|diff|branch|switch|checkout|merge|restore · vcs merge --abort
@@ -244,11 +244,39 @@ your own rules. The [CHANGELOG](./CHANGELOG.md) has the details.
244
244
  }
245
245
  ],
246
246
  "agents": [ { "handle": "@helper", "model": "...", "systemPrompt": "...", "enableChannel": "general" } ],
247
- "functions": [ { "name": "hello", "code": "export default { async fetch() { return new Response('hi'); } }" } ]
247
+ "functions": [ { "name": "hello", "code": "export default { async fetch() { return new Response('hi'); } }" } ],
248
+ "collections": [ { "name": "docs", "mode": "text", "fields": [ { "name": "category", "type": "string" } ] } ]
248
249
  }
249
250
  ```
250
251
 
251
252
  `provision` is idempotent — re-running updates tables/agents/functions in place.
253
+ A collection whose definition hasn't changed is left alone. `provision` doesn't
254
+ wait for a new collection to become ready. On a Free plan it skips collections
255
+ with a warning (vector search needs a paid plan) and carries on. A collection
256
+ definition can't change: if it differs from the existing one, `provision` stops
257
+ and tells you to run `muhkoo vectors rm <appId> <name>` (which deletes its
258
+ entries) before provisioning again.
259
+
260
+ ## Vector search
261
+
262
+ ```
263
+ muhkoo vectors ls <appId> [--json]
264
+ muhkoo vectors get <appId> <name> [--json]
265
+ muhkoo vectors create <appId> <name> --mode text|vectors [--model <id>] [--dimensions <n>] [--metric cosine|euclidean|dot-product] [--fields name:type,...] [--access app|backend] [--no-wait]
266
+ muhkoo vectors rm <appId> <name>
267
+ muhkoo vectors notices <appId> <name> --env live|test --spaces <id,...> [--default <id>]
268
+ muhkoo vectors query <name> (--text <query> | --vector <json>) [--topk <n>] [--filter <json>] [--with-text] [--key <app key>] [--json]
269
+ ```
270
+
271
+ A new collection can take a few minutes to become ready, so `create` waits up
272
+ to 10 minutes; pass `--no-wait` to return straight away and check later with
273
+ `vectors get`. Vector search needs a paid plan. `query` uses an app key
274
+ (`--key` or `MUHKOO_APP_KEY`) rather than your sign-in:
275
+
276
+ ```bash
277
+ muhkoo vectors create <appId> docs --mode text --fields category:string
278
+ muhkoo vectors query docs --text "forgot my password" --filter '{"category":"a"}' --key "$KEY"
279
+ ```
252
280
 
253
281
  ## License
254
282
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@muhkoo/cli",
3
- "version": "0.15.0-alpha.11",
3
+ "version": "0.15.0-alpha.13",
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",
@@ -43,7 +43,7 @@
43
43
  "release": "npm publish --tag alpha && npm dist-tag add @muhkoo/cli@$npm_package_version latest"
44
44
  },
45
45
  "dependencies": {
46
- "@muhkoo/connect": "0.15.0-alpha.11",
46
+ "@muhkoo/connect": "0.15.0-alpha.13",
47
47
  "snarkjs": "^0.7.0"
48
48
  },
49
49
  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e",
@@ -40,7 +40,9 @@ export default async function apps(args) {
40
40
 
41
41
  async function list(ctx, args) {
42
42
  const r = ensure(await devCall(ctx, "GET", "/api/apps"), "List apps");
43
- const apps = r.body?.apps || r.body || [];
43
+ // A deleted app stays in the account's list with `deletedAt` set; hide it,
44
+ // as the portal does. `apps get <appId>` still shows one, marked deleted.
45
+ const apps = (r.body?.apps || r.body || []).filter((a) => !a.deletedAt);
44
46
  if (args.json) return json(apps);
45
47
  if (!apps.length) return info("No apps yet. Create one with `muhkoo apps create --slug <name>`.");
46
48
  table(
@@ -57,6 +59,10 @@ async function get(ctx, args) {
57
59
  const a = r.body;
58
60
  info(`${c.bold("slug")} ${a.slug}`);
59
61
  info(`${c.bold("appId")} ${a.appId}`);
62
+ if (a.deletedAt) {
63
+ const d = new Date(a.deletedAt);
64
+ info(`${c.bold("deleted")} ${Number.isNaN(d.getTime()) ? String(a.deletedAt) : d.toISOString().slice(0, 10)}`);
65
+ }
60
66
  info(`${c.bold("origins")} ${a.allowedOrigins ?? "*"}`);
61
67
  info(`${c.bold("hosting")} https://${a.slug}.${appsSuffixFor(ctx.baseUrl)}`);
62
68
  if (Array.isArray(a.keys)) {
@@ -10,6 +10,7 @@
10
10
  * "allowedOrigins": "*",
11
11
  * "email": "you@example.com", // only to bootstrap a new developer
12
12
  * "tables": [ <DbTableSpec>, ... ],
13
+ * "collections": [ { "name": "docs", ...CollectionDefinition }, ... ], // vector search; not waited on
13
14
  * "agents": [ { ...AgentCreateInput, "enableChannel": "general" }, ... ],
14
15
  * "functions": [ { ...FunctionDeployInput, "enableChannel": "general"? }, ... ]
15
16
  * }
@@ -17,7 +18,7 @@
17
18
 
18
19
  import { readFile, writeFile, access, chmod } from "node:fs/promises";
19
20
  import { devContext } from "../lib/config.js";
20
- import { devCall, appKeyGet } from "../lib/http.js";
21
+ import { devCall, appKeyGet, ensure } from "../lib/http.js";
21
22
  import { appsSuffixFor } from "../lib/bases.js";
22
23
  import { step, ok, warn, info, die, c } from "../lib/ui.js";
23
24
 
@@ -66,6 +67,7 @@ export default async function provision(args) {
66
67
  const app = await createOrReuseApp(ctx, spec, prior, DRY);
67
68
  await applyHostingConfig(ctx, app.appId, spec, prior, DRY);
68
69
  const tables = await putTables(ctx, app.appId, spec.tables, DRY);
70
+ const collections = await putCollections(ctx, app.appId, spec.collections, DRY);
69
71
  const agents = await createAgents(ctx, app.appId, spec.agents, DRY);
70
72
  const functions = await deployFunctions(ctx, app.appId, spec.functions, DRY);
71
73
 
@@ -77,6 +79,7 @@ export default async function provision(args) {
77
79
  hostingUrl,
78
80
  keys: app.keys?.length ? app.keys : prior?.keys || [],
79
81
  tables,
82
+ collections,
80
83
  agents,
81
84
  functions,
82
85
  };
@@ -89,6 +92,10 @@ export default async function provision(args) {
89
92
  info(` slug: ${record.slug}`);
90
93
  if (pk) info(` test pk: ${pk}`);
91
94
  info(` tables: ${tables.join(", ") || "(none)"}`);
95
+ if (collections.length) {
96
+ const label = (x) => `${x.name} (${x.skipped || x.status || "dry run"})`;
97
+ info(` collections: ${collections.map(label).join(", ")}`);
98
+ }
92
99
  info(` hosting: ${hostingUrl} (run \`muhkoo deploy\` once your client is built)`);
93
100
  if ((agents || []).some((a) => a.enableChannel) || (functions || []).some((f) => f.enableChannel)) {
94
101
  info("", "Next: run the app once so its channels exist, then:");
@@ -161,6 +168,34 @@ async function putTables(ctx, appId, tables, DRY) {
161
168
  return done;
162
169
  }
163
170
 
171
+ /** PUT each vector collection definition. 202 = created, 200 = already the
172
+ * same definition. Doesn't wait for `ready` (that takes minutes). */
173
+ async function putCollections(ctx, appId, specs, DRY) {
174
+ const done = [];
175
+ for (const { name, ...definition } of specs || []) {
176
+ step(`Collection "${name}"…`);
177
+ if (DRY) {
178
+ done.push({ name });
179
+ continue;
180
+ }
181
+ const r = await devCall(ctx, "PUT", `/api/apps/${appId}/vectors/collections/${encodeURIComponent(name)}`, definition);
182
+ if (r.status === 402) {
183
+ warn(`Vector search needs a paid plan — skipped ${name}. (Config saved for later.)`);
184
+ done.push({ name, skipped: "paid-tier" });
185
+ continue;
186
+ }
187
+ if (r.status === 409 && r.body?.code === "collection_exists") {
188
+ die(
189
+ `Collection "${name}" already exists with a different definition. Definitions can't change: run \`muhkoo vectors rm ${appId} ${name}\` (deletes its entries), then provision again.`,
190
+ );
191
+ }
192
+ ensure(r, `Collection "${name}"`);
193
+ info(` ${c.green("✓")} ${name} (${r.status})`);
194
+ done.push({ name, status: r.status });
195
+ }
196
+ return done;
197
+ }
198
+
164
199
  async function createAgents(ctx, appId, agents, DRY) {
165
200
  const created = [];
166
201
  if (!(agents || []).length) return created;
@@ -20,6 +20,8 @@ const SCOPES = [
20
20
  "messages:write",
21
21
  "functions:invoke",
22
22
  "ai:infer",
23
+ "vectors:read",
24
+ "vectors:write",
23
25
  ];
24
26
 
25
27
  const DEFAULT_SCOPES = ["db:read", "db:write"];
@@ -0,0 +1,239 @@
1
+ /**
2
+ * `muhkoo vectors` — manage an app's vector search collections (owner
3
+ * session). Collections can also be created via `muhkoo provision`.
4
+ */
5
+
6
+ import { devContext, resolveBase } from "../lib/config.js";
7
+ import { devCall, skCall, ensure } from "../lib/http.js";
8
+ import { table, json, ok, info, step, die, printable, redact } from "../lib/ui.js";
9
+
10
+ export const help = `muhkoo vectors — vector search collections
11
+
12
+ Usage:
13
+ muhkoo vectors ls <appId> [--json]
14
+ muhkoo vectors get <appId> <name> [--json]
15
+ muhkoo vectors create <appId> <name> --mode text|vectors [--model <id>] [--dimensions <n>] [--metric cosine|euclidean|dot-product] [--fields name:type,...] [--access app|backend] [--no-wait]
16
+ muhkoo vectors rm <appId> <name>
17
+ muhkoo vectors notices <appId> <name> --env live|test --spaces <id,...> [--default <id>]
18
+ muhkoo vectors query <name> (--text <query> | --vector <json>) [--topk <n>] [--filter <json>] [--with-text] [--key <app key>] [--json]`;
19
+
20
+ const POLL_MS = 2000;
21
+ const WAIT_MS = 10 * 60 * 1000;
22
+
23
+ export default async function vectors(args) {
24
+ for (const p of args._) {
25
+ if (p.startsWith("-")) die(`Unknown option "${printable(p)}". Options use two dashes, e.g. --key.`);
26
+ }
27
+ const sub = args._[1];
28
+ if (sub === "query") return query(args);
29
+
30
+ const appId = args._[2] || args.app;
31
+ if (!appId) die("Missing app id. Usage: muhkoo vectors <ls|get|create|rm|notices> <appId> [name]");
32
+
33
+ switch (sub) {
34
+ case "ls":
35
+ case undefined:
36
+ return list(await devContext(args), appId, args);
37
+ case "get":
38
+ return get(await devContext(args), appId, args);
39
+ case "create":
40
+ return create(args, appId);
41
+ case "rm":
42
+ return remove(await devContext(args), appId, args);
43
+ case "notices":
44
+ return notices(args, appId);
45
+ default:
46
+ die(`Unknown subcommand "vectors ${sub}". See \`muhkoo vectors --help\`.`);
47
+ }
48
+ }
49
+
50
+ const base = (appId) => `/api/apps/${encodeURIComponent(appId)}/vectors/collections`;
51
+ const one = (appId, name) => `${base(appId)}/${encodeURIComponent(name)}`;
52
+ const count = (n) => (n === null || n === undefined ? "—" : String(n));
53
+
54
+ function nameArg(args, usage) {
55
+ const name = args._[3];
56
+ if (!name) die(`Usage: ${usage}`);
57
+ return name;
58
+ }
59
+
60
+ async function list(ctx, appId, args) {
61
+ const r = ensure(await devCall(ctx, "GET", base(appId)), "List collections");
62
+ const items = r.body?.collections || [];
63
+ if (args.json) return json(items);
64
+ if (!items.length) return info("No collections. Create one with `muhkoo vectors create`.");
65
+ table(
66
+ ["NAME", "MODE", "MODEL/DIMS", "ACCESS", "STATUS", "LIVE", "TEST"],
67
+ items.map((c) => [
68
+ c.name,
69
+ c.mode,
70
+ c.mode === "text" ? c.model : c.dimensions,
71
+ c.access,
72
+ c.status,
73
+ count(c.envs?.live?.entries),
74
+ count(c.envs?.test?.entries),
75
+ ]),
76
+ );
77
+ }
78
+
79
+ async function get(ctx, appId, args) {
80
+ const name = nameArg(args, "muhkoo vectors get <appId> <name>");
81
+ const r = ensure(await devCall(ctx, "GET", one(appId, name)), "Get collection");
82
+ json(r.body);
83
+ }
84
+
85
+ function parseFields(spec) {
86
+ if (spec === true) die("--fields needs a value, e.g. --fields category:string,year:number");
87
+ return String(spec)
88
+ .split(",")
89
+ .filter((s) => s !== "")
90
+ .map((item) => {
91
+ const m = /^([^:]+):([^:]+)$/.exec(item);
92
+ if (!m) die(`Malformed field "${printable(item)}" in --fields. Use name:type, e.g. category:string.`);
93
+ return { name: m[1], type: m[2] };
94
+ });
95
+ }
96
+
97
+ function definition(args) {
98
+ if (!args.mode || args.mode === true) die("Missing --mode text|vectors.");
99
+ const body = { mode: args.mode };
100
+ if (args.model !== undefined) body.model = args.model;
101
+ if (args.dimensions !== undefined) {
102
+ const n = Number(args.dimensions);
103
+ if (!Number.isFinite(n)) die(`--dimensions must be a number, not "${printable(args.dimensions)}".`);
104
+ body.dimensions = n;
105
+ }
106
+ if (args.metric !== undefined) body.metric = args.metric;
107
+ if (args.fields !== undefined) body.fields = parseFields(args.fields);
108
+ if (args.access !== undefined) body.access = args.access;
109
+ return body;
110
+ }
111
+
112
+ /** Like ensure(), but a `{ error, code }` body prints the server's sentence
113
+ * and code (plus Retry-After on a 429) instead of raw JSON. */
114
+ function serverFail(r, what) {
115
+ if (r.ok) return r;
116
+ const b = r.body;
117
+ if (!b || typeof b !== "object" || !b.error) return ensure(r, what);
118
+ let msg = `${what} failed (${r.status}): ${redact(String(b.error))}`;
119
+ if (b.code) msg += ` (${redact(String(b.code))})`;
120
+ if (r.status === 429 && r.retryAfter != null) msg += ` Retry after ${redact(String(r.retryAfter))} seconds.`;
121
+ die(msg);
122
+ }
123
+
124
+ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
125
+
126
+ async function create(args, appId) {
127
+ const usage = "muhkoo vectors create <appId> <name> --mode text|vectors";
128
+ const name = nameArg(args, usage);
129
+ const body = definition(args);
130
+ const ctx = await devContext(args);
131
+ const put = await devCall(ctx, "PUT", one(appId, name), body);
132
+ if (put.status === 402) die(String(put.body?.error || "Vector search requires a paid plan."));
133
+ serverFail(put, "Create collection");
134
+ if (args["no-wait"]) return ok(`Creating collection ${name}.`);
135
+
136
+ let last = null;
137
+ const started = Date.now();
138
+ let c = put.body;
139
+ for (;;) {
140
+ const status = c?.status;
141
+ if (status !== last) {
142
+ step(`${name}: ${status}`);
143
+ last = status;
144
+ }
145
+ if (status === "ready") return ok(`Collection ${name} is ready.`);
146
+ if (status === "failed") {
147
+ for (const [env, e] of Object.entries(c.envs || {})) {
148
+ if (e?.error) info(` ${env}: ${e.error}`);
149
+ }
150
+ die(`Collection ${name} failed to create.`);
151
+ }
152
+ if (Date.now() - started >= WAIT_MS) break;
153
+ await sleep(POLL_MS);
154
+ c = ensure(await devCall(ctx, "GET", one(appId, name)), "Get collection").body;
155
+ }
156
+ die(`Still creating after 10 minutes; check with \`muhkoo vectors get ${appId} ${name}\`.`);
157
+ }
158
+
159
+ async function remove(ctx, appId, args) {
160
+ const name = nameArg(args, "muhkoo vectors rm <appId> <name>");
161
+ serverFail(await devCall(ctx, "DELETE", one(appId, name)), "Drop collection");
162
+ ok(`Dropping collection ${name}; its entries in test and live are deleted.`);
163
+ }
164
+
165
+ function jsonFlag(args, flag) {
166
+ const raw = args[flag];
167
+ if (raw === true) die(`--${flag} needs a JSON value.`);
168
+ try {
169
+ return JSON.parse(String(raw));
170
+ } catch (e) {
171
+ die(`--${flag} is not valid JSON: ${e.message}`);
172
+ }
173
+ }
174
+
175
+ const cut = (s, n = 60) => (s.length > n ? s.slice(0, n - 1) + "…" : s);
176
+
177
+ /** Debugging search over the data API, with an app key (no session). */
178
+ async function query(args) {
179
+ const name = args._[2];
180
+ if (!name) die("Usage: muhkoo vectors query <name> (--text <query> | --vector <json>)");
181
+ const hasText = args.text !== undefined;
182
+ const hasVector = args.vector !== undefined;
183
+ if (hasText === hasVector) die("Pass exactly one of --text and --vector.");
184
+ const key = args.key && args.key !== true ? String(args.key) : process.env.MUHKOO_APP_KEY;
185
+ if (!key) die("No app key. Pass --key <mk_…> or set MUHKOO_APP_KEY (`muhkoo tokens create` mints one).");
186
+
187
+ const body = {};
188
+ if (hasText) {
189
+ if (args.text === true) die("--text needs a value.");
190
+ body.text = String(args.text);
191
+ } else {
192
+ body.vector = jsonFlag(args, "vector");
193
+ }
194
+ if (args.topk !== undefined) {
195
+ const n = Number(args.topk);
196
+ if (args.topk === true || !Number.isFinite(n)) die(`--topk must be a number, not "${printable(args.topk)}".`);
197
+ body.topK = n;
198
+ }
199
+ if (args.filter !== undefined) body.filter = jsonFlag(args, "filter");
200
+ if (args["with-text"]) body.includeText = true;
201
+
202
+ const baseUrl = await resolveBase(args);
203
+ const r = await skCall(baseUrl, key, "POST", `/api/vectors/${encodeURIComponent(name)}/query`, body);
204
+ if (!r.ok) {
205
+ const msg = r.body && typeof r.body === "object" && r.body.error ? r.body.error : r.body;
206
+ die(`Query failed (${r.status}): ${redact(msg ?? "no response body")}`);
207
+ }
208
+ const matches = r.body?.matches || [];
209
+ if (args.json) return json(matches);
210
+ if (!matches.length) return info("No matches.");
211
+ const withText = Boolean(args["with-text"]);
212
+ const headers = withText ? ["ID", "SCORE", "DATA", "TEXT"] : ["ID", "SCORE", "DATA"];
213
+ table(
214
+ headers,
215
+ matches.map((m) => {
216
+ const row = [m.id, String(m.score), m.data === undefined ? "" : cut(JSON.stringify(m.data))];
217
+ if (withText) row.push(m.text == null ? "" : cut(String(m.text)));
218
+ return row;
219
+ }),
220
+ );
221
+ }
222
+
223
+ async function notices(args, appId) {
224
+ const name = nameArg(args, "muhkoo vectors notices <appId> <name> --env live|test --spaces <id,...>");
225
+ if (args.env !== "live" && args.env !== "test") die("--env must be live or test.");
226
+ if (args.spaces === undefined || args.spaces === true) die('Missing --spaces <id,...> (pass --spaces "" to clear).');
227
+ const spaces = String(args.spaces).split(",").filter((s) => s !== "");
228
+ let defaultSpace = null;
229
+ if (args.default !== undefined) {
230
+ defaultSpace = String(args.default);
231
+ if (!spaces.includes(defaultSpace)) die(`--default "${printable(defaultSpace)}" must be one of the --spaces.`);
232
+ }
233
+ const ctx = await devContext(args);
234
+ ensure(
235
+ await devCall(ctx, "PATCH", `${one(appId, name)}/notices?env=${args.env}`, { spaces, defaultSpace }),
236
+ "Set notice Spaces",
237
+ );
238
+ ok(`Notice Spaces for ${name} (${args.env}): ${spaces.length ? spaces.join(", ") : "none"}.`);
239
+ }
package/src/index.js CHANGED
@@ -27,6 +27,7 @@ const COMMANDS = {
27
27
  hosting: () => import("./commands/hosting.js"),
28
28
  domains: () => import("./commands/domains.js"),
29
29
  tables: () => import("./commands/tables.js"),
30
+ vectors: () => import("./commands/vectors.js"),
30
31
  agents: () => import("./commands/agents.js"),
31
32
  functions: () => import("./commands/functions.js"),
32
33
  logs: () => import("./commands/logs.js"),
@@ -52,6 +53,7 @@ Apps
52
53
  Backend
53
54
  provision --spec <f> create/update tables, agents, functions from a spec
54
55
  tables ls|get|rm inspect database tables
56
+ vectors ls|get|create|rm|notices|query vector search collections
55
57
  agents ls|get|rm|enable|disable|models
56
58
  functions ls|get|code|deploy|rm|enable|disable
57
59
 
package/src/lib/http.js CHANGED
@@ -26,7 +26,10 @@ async function request(baseUrl, method, path, { auth, body, raw } = {}) {
26
26
  } catch {
27
27
  parsed = text;
28
28
  }
29
- return { ok: res.ok, status: res.status, body: parsed };
29
+ const result = { ok: res.ok, status: res.status, body: parsed };
30
+ const retryAfter = res.headers?.get?.("Retry-After");
31
+ if (retryAfter != null) result.retryAfter = retryAfter;
32
+ return result;
30
33
  }
31
34
 
32
35
  /** A management call authenticated with a developer session token (Bearer). */