@w6w/cli 0.1.0

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.
Files changed (71) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +110 -0
  3. package/dist/bin/w6w.d.ts +22 -0
  4. package/dist/bin/w6w.d.ts.map +1 -0
  5. package/dist/bin/w6w.js +58 -0
  6. package/dist/bin/w6w.js.map +1 -0
  7. package/dist/mod.d.ts +131 -0
  8. package/dist/mod.d.ts.map +1 -0
  9. package/dist/mod.js +257 -0
  10. package/dist/mod.js.map +1 -0
  11. package/dist/src/args.d.ts +79 -0
  12. package/dist/src/args.d.ts.map +1 -0
  13. package/dist/src/args.js +130 -0
  14. package/dist/src/args.js.map +1 -0
  15. package/dist/src/client.d.ts +90 -0
  16. package/dist/src/client.d.ts.map +1 -0
  17. package/dist/src/client.js +172 -0
  18. package/dist/src/client.js.map +1 -0
  19. package/dist/src/commands/connections.d.ts +13 -0
  20. package/dist/src/commands/connections.d.ts.map +1 -0
  21. package/dist/src/commands/connections.js +30 -0
  22. package/dist/src/commands/connections.js.map +1 -0
  23. package/dist/src/commands/documents.d.ts +34 -0
  24. package/dist/src/commands/documents.d.ts.map +1 -0
  25. package/dist/src/commands/documents.js +179 -0
  26. package/dist/src/commands/documents.js.map +1 -0
  27. package/dist/src/commands/index.d.ts +27 -0
  28. package/dist/src/commands/index.d.ts.map +1 -0
  29. package/dist/src/commands/index.js +39 -0
  30. package/dist/src/commands/index.js.map +1 -0
  31. package/dist/src/commands/me.d.ts +29 -0
  32. package/dist/src/commands/me.d.ts.map +1 -0
  33. package/dist/src/commands/me.js +52 -0
  34. package/dist/src/commands/me.js.map +1 -0
  35. package/dist/src/commands/run.d.ts +24 -0
  36. package/dist/src/commands/run.d.ts.map +1 -0
  37. package/dist/src/commands/run.js +78 -0
  38. package/dist/src/commands/run.js.map +1 -0
  39. package/dist/src/commands/shared.d.ts +117 -0
  40. package/dist/src/commands/shared.d.ts.map +1 -0
  41. package/dist/src/commands/shared.js +152 -0
  42. package/dist/src/commands/shared.js.map +1 -0
  43. package/dist/src/commands/vars.d.ts +59 -0
  44. package/dist/src/commands/vars.d.ts.map +1 -0
  45. package/dist/src/commands/vars.js +216 -0
  46. package/dist/src/commands/vars.js.map +1 -0
  47. package/dist/src/commands/workflows.d.ts +13 -0
  48. package/dist/src/commands/workflows.d.ts.map +1 -0
  49. package/dist/src/commands/workflows.js +75 -0
  50. package/dist/src/commands/workflows.js.map +1 -0
  51. package/dist/src/exit.d.ts +51 -0
  52. package/dist/src/exit.d.ts.map +1 -0
  53. package/dist/src/exit.js +94 -0
  54. package/dist/src/exit.js.map +1 -0
  55. package/dist/src/help.d.ts +48 -0
  56. package/dist/src/help.d.ts.map +1 -0
  57. package/dist/src/help.generated.d.ts +88 -0
  58. package/dist/src/help.generated.d.ts.map +1 -0
  59. package/dist/src/help.generated.js +988 -0
  60. package/dist/src/help.generated.js.map +1 -0
  61. package/dist/src/help.js +128 -0
  62. package/dist/src/help.js.map +1 -0
  63. package/dist/src/output.d.ts +84 -0
  64. package/dist/src/output.d.ts.map +1 -0
  65. package/dist/src/output.js +94 -0
  66. package/dist/src/output.js.map +1 -0
  67. package/dist/src/runtime.d.ts +37 -0
  68. package/dist/src/runtime.d.ts.map +1 -0
  69. package/dist/src/runtime.js +57 -0
  70. package/dist/src/runtime.js.map +1 -0
  71. package/package.json +42 -0
@@ -0,0 +1,179 @@
1
+ /**
2
+ * `w6w documents …` — the document store at the command line.
3
+ *
4
+ * Six commands, **one SDK call each**. Nothing here composes two requests,
5
+ * filters a list, sorts a result or resolves a key by scanning: a wrapper that
6
+ * has to compose two calls is describing an operation that belongs in the API
7
+ * (`README.md`, "What a wrapper is"), and the CLI is a wrapper like the other
8
+ * two. Addressing mirrors the server exactly — **create by `key`, read by id or
9
+ * by key, update and delete by id** (`docs/implementation.md` §7).
10
+ *
11
+ * Everything a handler does falls into four steps, in this order: read its own
12
+ * arguments, call one method on `client.documents`, render, return. Errors are
13
+ * not caught here — `main()` reports a throw once, on stderr, and maps it to an
14
+ * exit code through `src/exit.ts`, so an `ApiError` exits 2 and a usage error
15
+ * exits 1 without any command deciding that for itself.
16
+ *
17
+ * **`--project` belongs to this group and not to `w6w vars`.** Documents are
18
+ * project-scoped and every route below takes an optional `?project=`; variables
19
+ * are not, and `src/commands/vars.ts` refuses the flag rather than accepting one
20
+ * the server would ignore.
21
+ *
22
+ * @module
23
+ */
24
+ import { argument, noExtraArguments, requiredFlag, table, textFlag } from "./shared.js";
25
+ /**
26
+ * The project scope for one call: the `--project` flag, or nothing at all.
27
+ *
28
+ * Nothing is the important case — an omitted `?project=` is how the caller asks
29
+ * the server for the account's default project, so an absent flag must not
30
+ * become an empty string or a guess.
31
+ */
32
+ function scope(context) {
33
+ const project = textFlag(context, "project");
34
+ return project === undefined ? {} : { project };
35
+ }
36
+ /**
37
+ * The `--format` flag, as the SDK's format hint.
38
+ *
39
+ * Cast rather than checked: the set of formats is the **server's** rule
40
+ * (`400 invalid_format` when it is broken), and a copy of that enum in the CLI
41
+ * would go stale the day a sixth format is added, rejecting locally a value the
42
+ * server had just started accepting.
43
+ */
44
+ function format(context) {
45
+ return textFlag(context, "format");
46
+ }
47
+ /** One document, as a table row. */
48
+ function row(doc) {
49
+ return [doc.id, doc.key, doc.format, doc.updatedAt];
50
+ }
51
+ /** The listing: one line per document, or a line saying there are none. */
52
+ function renderList(docs, styles) {
53
+ if (docs.length === 0)
54
+ return styles.dim("No documents.");
55
+ return table(["ID", "KEY", "FORMAT", "UPDATED"], docs.map(row), styles);
56
+ }
57
+ /** One document in full — the content is what the reader came for, so it is shown. */
58
+ function renderDoc(doc, styles) {
59
+ const heading = `${styles.bold(doc.key)} ${styles.dim(`(${doc.id})`)}`;
60
+ const meta = styles.dim(`${doc.format} · updated ${doc.updatedAt}`);
61
+ const description = doc.description.length > 0 ? [doc.description] : [];
62
+ return [heading, meta, ...description, "", doc.content].join("\n");
63
+ }
64
+ /** The confirmation for a write: what changed, and how to address it next time. */
65
+ function renderWrite(verb, doc, styles) {
66
+ return `${verb} ${styles.bold(doc.key)} ${styles.dim(`(${doc.id})`)}`;
67
+ }
68
+ const list = async (context) => {
69
+ noExtraArguments(context, 0);
70
+ const docs = await context.client().documents.list(scope(context));
71
+ context.out.emit(docs, (styles) => renderList(docs, styles));
72
+ };
73
+ const get = async (context) => {
74
+ const id = argument(context, 0, "a document id (see: `w6w documents list`)");
75
+ noExtraArguments(context, 1);
76
+ const doc = await context.client().documents.get(id, scope(context));
77
+ context.out.emit(doc, (styles) => renderDoc(doc, styles));
78
+ };
79
+ /**
80
+ * `w6w documents get-by-key <key>` — the key-addressed read.
81
+ *
82
+ * The key is handed to the SDK untouched, which percent-encodes it at
83
+ * interpolation. **No key is rejected here**, and that is deliberate: the server
84
+ * accepts any non-empty key up to 128 characters, so refusing one locally would
85
+ * make a document that a user legitimately created permanently unreadable
86
+ * through this CLI.
87
+ *
88
+ * **This lane's `".."` behaviour, stated rather than papered over (D1).** A key
89
+ * of `"."` or `".."` is creatable, and it is *not* addressable from this
90
+ * runtime. Percent-encoding cannot help — `.` is unreserved in RFC 3986, so
91
+ * `encodeURIComponent("..")` is still `".."` — and the WHATWG URL parser behind
92
+ * `fetch`, which this lane and the node SDK share, removes dot segments while
93
+ * building the request: `…/api/documents/by-key/..` is normalised to
94
+ * `…/api/documents/`, the **list** route. The list route answers `200` with a
95
+ * `documents` array, the SDK finds no `document` key in it, and the caller gets
96
+ * an `ApiError` with code `bad_response` (D3) and exit code 2 — a loud failure,
97
+ * not a silent wrong answer.
98
+ *
99
+ * The Python wrapper's `urllib` sends the same path **literally** and does not
100
+ * normalise it, so the two lanes reach different routes for the same key. That
101
+ * divergence is measured, not theoretical, and it is resolved server-side by the
102
+ * `by-key` route landing in T4.4.1; neither wrapper works around it.
103
+ */
104
+ const getByKey = async (context) => {
105
+ const key = argument(context, 0, "a document key (the name it was created under)");
106
+ noExtraArguments(context, 1);
107
+ const doc = await context.client().documents.getByKey(key, scope(context));
108
+ context.out.emit(doc, (styles) => renderDoc(doc, styles));
109
+ };
110
+ const create = async (context) => {
111
+ const key = argument(context, 0, "a document key to create (unique per project)");
112
+ noExtraArguments(context, 1);
113
+ const doc = await context.client().documents.create({
114
+ key,
115
+ content: requiredFlag(context, "content", "--content <text>"),
116
+ format: format(context),
117
+ description: textFlag(context, "description"),
118
+ }, scope(context));
119
+ context.out.emit(doc, (styles) => renderWrite("Created", doc, styles));
120
+ };
121
+ /**
122
+ * `w6w documents update <id>` — a patch, addressed by the server-issued id.
123
+ *
124
+ * **Only flags the user typed reach the wire (D2).** The patch is assembled
125
+ * field by field, and a field whose flag was absent is never added — so
126
+ * `w6w documents update doc_1 --format markdown` sends `{"format":"markdown"}`
127
+ * and leaves the content alone, while `w6w documents update doc_1` alone sends
128
+ * `{}` and changes nothing. Assigning `undefined` (or worse, `null`) to the
129
+ * missing fields would turn "don't touch this" into "blank this out", which is
130
+ * the kind of bug that is only ever found after it has run.
131
+ */
132
+ const update = async (context) => {
133
+ const id = argument(context, 0, "the document id to update (see: `w6w documents list`)");
134
+ noExtraArguments(context, 1);
135
+ const patch = {};
136
+ const content = textFlag(context, "content");
137
+ if (content !== undefined)
138
+ patch.content = content;
139
+ const hint = format(context);
140
+ if (hint !== undefined)
141
+ patch.format = hint;
142
+ const description = textFlag(context, "description");
143
+ if (description !== undefined)
144
+ patch.description = description;
145
+ const doc = await context.client().documents.update(id, patch, scope(context));
146
+ context.out.emit(doc, (styles) => renderWrite("Updated", doc, styles));
147
+ };
148
+ /**
149
+ * `w6w documents delete <id>` — and **nothing on stdout**.
150
+ *
151
+ * The server answers `{ok:true}`; the wrapper contract unwraps that to nothing
152
+ * at all (`docs/implementation.md` §6), so the only machine-readable part of the
153
+ * answer is the exit code. The human gets a confirmation through `note()`, which
154
+ * `--json` suppresses — `w6w documents delete doc_1 --json` prints an empty
155
+ * stdout rather than a payload the contract says does not exist.
156
+ */
157
+ const remove = async (context) => {
158
+ const id = argument(context, 0, "the document id to delete (see: `w6w documents list`)");
159
+ noExtraArguments(context, 1);
160
+ await context.client().documents.delete(id, scope(context));
161
+ context.out.note(`Deleted ${id}.`);
162
+ };
163
+ /**
164
+ * The six `w6w documents` commands, keyed by the canonical command path.
165
+ *
166
+ * The keys are the generated help tree's `path` values joined by a space, which
167
+ * are `endpoints.json`'s `naming.cli` spellings — `tests/cmd_documents_test.ts`
168
+ * asserts the two sets are the same, so a command cannot be registered under a
169
+ * name the help does not document, or documented under a name nothing runs.
170
+ */
171
+ export const DOCUMENT_COMMANDS = {
172
+ "documents list": list,
173
+ "documents get": get,
174
+ "documents get-by-key": getByKey,
175
+ "documents create": create,
176
+ "documents update": update,
177
+ "documents delete": remove,
178
+ };
179
+ //# sourceMappingURL=documents.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"documents.js","sourceRoot":"","sources":["../../../src/commands/documents.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,27 @@
1
+ /**
2
+ * The command registry — every command this build can run, in one map.
3
+ *
4
+ * `main()` dispatches by canonical command path (`"documents list"`,
5
+ * `"vars get-by-name"`), so this file is a union of the per-group registries and
6
+ * nothing else: no logic, no ordering, no conditionals. A command group owns its
7
+ * handlers, its arguments and its help; joining them is all that happens here.
8
+ *
9
+ * **This is the merge point.** Each command-group node adds one import and one
10
+ * spread, and nothing else in the file moves — which is what keeps two groups
11
+ * landing in the same release from conflicting over it. A group that is not
12
+ * spread in below is not runnable: `main()` answers a command with no handler
13
+ * with a usage error saying it is not available in this build, which is a better
14
+ * answer than a silent success.
15
+ *
16
+ * @module
17
+ */
18
+ import type { CommandRegistry } from "../../mod.ts";
19
+ export { DOCUMENT_COMMANDS } from "./documents.ts";
20
+ export { VAR_COMMANDS } from "./vars.ts";
21
+ export { ME_COMMANDS } from "./me.ts";
22
+ export { CONNECTION_COMMANDS } from "./connections.ts";
23
+ export { WORKFLOW_COMMANDS } from "./workflows.ts";
24
+ export { RUN_COMMANDS } from "./run.ts";
25
+ /** Every wired command, keyed by canonical command path. */
26
+ export declare const COMMANDS: CommandRegistry;
27
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAQpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,4DAA4D;AAC5D,eAAO,MAAM,QAAQ,EAAE,eAOtB,CAAC"}
@@ -0,0 +1,39 @@
1
+ /**
2
+ * The command registry — every command this build can run, in one map.
3
+ *
4
+ * `main()` dispatches by canonical command path (`"documents list"`,
5
+ * `"vars get-by-name"`), so this file is a union of the per-group registries and
6
+ * nothing else: no logic, no ordering, no conditionals. A command group owns its
7
+ * handlers, its arguments and its help; joining them is all that happens here.
8
+ *
9
+ * **This is the merge point.** Each command-group node adds one import and one
10
+ * spread, and nothing else in the file moves — which is what keeps two groups
11
+ * landing in the same release from conflicting over it. A group that is not
12
+ * spread in below is not runnable: `main()` answers a command with no handler
13
+ * with a usage error saying it is not available in this build, which is a better
14
+ * answer than a silent success.
15
+ *
16
+ * @module
17
+ */
18
+ import { DOCUMENT_COMMANDS } from "./documents.js";
19
+ import { VAR_COMMANDS } from "./vars.js";
20
+ import { ME_COMMANDS } from "./me.js";
21
+ import { CONNECTION_COMMANDS } from "./connections.js";
22
+ import { WORKFLOW_COMMANDS } from "./workflows.js";
23
+ import { RUN_COMMANDS } from "./run.js";
24
+ export { DOCUMENT_COMMANDS } from "./documents.js";
25
+ export { VAR_COMMANDS } from "./vars.js";
26
+ export { ME_COMMANDS } from "./me.js";
27
+ export { CONNECTION_COMMANDS } from "./connections.js";
28
+ export { WORKFLOW_COMMANDS } from "./workflows.js";
29
+ export { RUN_COMMANDS } from "./run.js";
30
+ /** Every wired command, keyed by canonical command path. */
31
+ export const COMMANDS = {
32
+ ...DOCUMENT_COMMANDS,
33
+ ...VAR_COMMANDS,
34
+ ...ME_COMMANDS,
35
+ ...CONNECTION_COMMANDS,
36
+ ...WORKFLOW_COMMANDS,
37
+ ...RUN_COMMANDS,
38
+ };
39
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,4DAA4D;AAC5D,MAAM,CAAC,MAAM,QAAQ,GAAoB;IACvC,GAAG,iBAAiB;IACpB,GAAG,YAAY;IACf,GAAG,WAAW;IACd,GAAG,mBAAmB;IACtB,GAAG,iBAAiB;IACpB,GAAG,YAAY;CAChB,CAAC"}
@@ -0,0 +1,29 @@
1
+ /**
2
+ * `w6w me` (alias `w6w info`, D8) — the caller's identity plus w6w component
3
+ * versions.
4
+ *
5
+ * One command, one SDK call — `client.me()`, which calls `GET /auth/me`, the
6
+ * server's real identity route (verified live 2026-07-28). The `versions`
7
+ * block does not exist server-side yet, so it is absent or partial against a
8
+ * live server today; every wrapper tolerates that.
9
+ *
10
+ * **Display is a separate rule from what the data carries (D5).** The
11
+ * `--json` payload is a faithful transcription of the wire: precedence is
12
+ * server-wins, so a server-supplied `versions.wrapper: "0.0.0"` reaches the
13
+ * caller unaltered — `context.out.emit`'s first argument is the raw `Me`
14
+ * object, untouched. The human-readable table never shows a literal `0.0.0`
15
+ * or an empty string for any version, though; it shows `dev` instead. That
16
+ * substitution happens only inside `renderMe`.
17
+ *
18
+ * @module
19
+ */
20
+ import type { CommandRegistry } from "../../mod.ts";
21
+ /**
22
+ * The one `w6w me` command. `w6w info` reaches the same handler: `resolve()`
23
+ * maps the alias back to the canonical `HelpCommand` before dispatch, and
24
+ * dispatch looks the handler up by `command.path.join(" ")` — always `"me"`,
25
+ * never `"info"` — so a second registry entry keyed `"info"` would be dead
26
+ * code, not a second alias.
27
+ */
28
+ export declare const ME_COMMANDS: CommandRegistry;
29
+ //# sourceMappingURL=me.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"me.d.ts","sourceRoot":"","sources":["../../../src/commands/me.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAkB,eAAe,EAAE,MAAM,cAAc,CAAC;AA6BpE;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,eAEzB,CAAC"}
@@ -0,0 +1,52 @@
1
+ /**
2
+ * `w6w me` (alias `w6w info`, D8) — the caller's identity plus w6w component
3
+ * versions.
4
+ *
5
+ * One command, one SDK call — `client.me()`, which calls `GET /auth/me`, the
6
+ * server's real identity route (verified live 2026-07-28). The `versions`
7
+ * block does not exist server-side yet, so it is absent or partial against a
8
+ * live server today; every wrapper tolerates that.
9
+ *
10
+ * **Display is a separate rule from what the data carries (D5).** The
11
+ * `--json` payload is a faithful transcription of the wire: precedence is
12
+ * server-wins, so a server-supplied `versions.wrapper: "0.0.0"` reaches the
13
+ * caller unaltered — `context.out.emit`'s first argument is the raw `Me`
14
+ * object, untouched. The human-readable table never shows a literal `0.0.0`
15
+ * or an empty string for any version, though; it shows `dev` instead. That
16
+ * substitution happens only inside `renderMe`.
17
+ *
18
+ * @module
19
+ */
20
+ import { noExtraArguments } from "./shared.js";
21
+ /** D5 — a version of `"0.0.0"` or `""` is never shown; the display is `"dev"`. */
22
+ function displayVersion(value) {
23
+ return value === "0.0.0" || value === "" ? "dev" : value;
24
+ }
25
+ /** The caller's identity, plus versions when the server reports any. */
26
+ function renderMe(me, styles) {
27
+ const lines = [`${styles.bold(me.tenant)} · ${me.account} · ${me.subject} (${me.role})`];
28
+ const versions = me.versions;
29
+ if (versions && Object.keys(versions).length > 0) {
30
+ lines.push("", styles.dim("versions:"));
31
+ for (const [component, version] of Object.entries(versions)) {
32
+ lines.push(` ${component}: ${displayVersion(version)}`);
33
+ }
34
+ }
35
+ return lines.join("\n");
36
+ }
37
+ const me = async (context) => {
38
+ noExtraArguments(context, 0);
39
+ const identity = await context.client().me();
40
+ context.out.emit(identity, (styles) => renderMe(identity, styles));
41
+ };
42
+ /**
43
+ * The one `w6w me` command. `w6w info` reaches the same handler: `resolve()`
44
+ * maps the alias back to the canonical `HelpCommand` before dispatch, and
45
+ * dispatch looks the handler up by `command.path.join(" ")` — always `"me"`,
46
+ * never `"info"` — so a second registry entry keyed `"info"` would be dead
47
+ * code, not a second alias.
48
+ */
49
+ export const ME_COMMANDS = {
50
+ "me": me,
51
+ };
52
+ //# sourceMappingURL=me.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"me.js","sourceRoot":"","sources":["../../../src/commands/me.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,kFAAkF;AAClF,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;AAC3D,CAAC;AAED,wEAAwE;AACxE,SAAS,QAAQ,CAAC,EAAM,EAAE,MAAc;IACtC,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,MAAM,EAAE,CAAC,OAAO,KAAK,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC;IACzF,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAC;IAC7B,IAAI,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjD,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC;QACxC,KAAK,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5D,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS,KAAK,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,EAAE,GAAmB,KAAK,EAAE,OAAO,EAAE,EAAE;IAC3C,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC7B,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;IAC7C,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AACrE,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAoB;IAC1C,IAAI,EAAE,EAAE;CACT,CAAC"}
@@ -0,0 +1,24 @@
1
+ /**
2
+ * `w6w run <urn> [--action <a>] [--payload <json>]` — run anything a URN
3
+ * addresses: a connection action, a function, an endpoint or a workflow
4
+ * (D16).
5
+ *
6
+ * One command, one SDK call, no envelope key to unwrap — `client.run()`
7
+ * already returns the kind-tagged `RunEnvelope` verbatim. This command's only
8
+ * job is turning `--payload` from a command-line string into the JSON object
9
+ * the operation's body takes, and rendering whichever arm came back.
10
+ *
11
+ * **A `kind` this build has never heard of is shown, not rejected** —
12
+ * `docs/implementation.md` §5, mirrored here rather than re-litigated: the
13
+ * server may grow a fourth arm before the wrappers do, on the one operation
14
+ * whose entire job is dispatch, and a client that raised on it would turn a
15
+ * forward-compatible server change into a hard breakage. `isActionRun` /
16
+ * `isFunctionRun` / `isWorkflowRun` narrow the three known arms; anything
17
+ * else falls to a plain `kind: …` line plus the raw JSON, exactly as the SDK
18
+ * handed it back.
19
+ *
20
+ * @module
21
+ */
22
+ import type { CommandRegistry } from "../../mod.ts";
23
+ export declare const RUN_COMMANDS: CommandRegistry;
24
+ //# sourceMappingURL=run.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/commands/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAkC,eAAe,EAAE,MAAM,cAAc,CAAC;AA6DpF,eAAO,MAAM,YAAY,EAAE,eAE1B,CAAC"}
@@ -0,0 +1,78 @@
1
+ /**
2
+ * `w6w run <urn> [--action <a>] [--payload <json>]` — run anything a URN
3
+ * addresses: a connection action, a function, an endpoint or a workflow
4
+ * (D16).
5
+ *
6
+ * One command, one SDK call, no envelope key to unwrap — `client.run()`
7
+ * already returns the kind-tagged `RunEnvelope` verbatim. This command's only
8
+ * job is turning `--payload` from a command-line string into the JSON object
9
+ * the operation's body takes, and rendering whichever arm came back.
10
+ *
11
+ * **A `kind` this build has never heard of is shown, not rejected** —
12
+ * `docs/implementation.md` §5, mirrored here rather than re-litigated: the
13
+ * server may grow a fourth arm before the wrappers do, on the one operation
14
+ * whose entire job is dispatch, and a client that raised on it would turn a
15
+ * forward-compatible server change into a hard breakage. `isActionRun` /
16
+ * `isFunctionRun` / `isWorkflowRun` narrow the three known arms; anything
17
+ * else falls to a plain `kind: …` line plus the raw JSON, exactly as the SDK
18
+ * handed it back.
19
+ *
20
+ * @module
21
+ */
22
+ import { isActionRun, isFunctionRun, isWorkflowRun } from "@w6w/sdk";
23
+ import { argument, noExtraArguments, textFlag, usageError } from "./shared.js";
24
+ /**
25
+ * `--payload <json>` as the object the operation's body takes.
26
+ *
27
+ * Unlike `w6w vars`' `--value` (which falls back to a bare string when it does
28
+ * not parse as JSON, because a var's value legitimately can be one), `run`'s
29
+ * payload is declared `type: "object"` in `endpoints.json` — there is no
30
+ * string arm to fall back to, so a value that fails to parse is a usage
31
+ * error, not a guess.
32
+ */
33
+ function payload(context) {
34
+ const text = textFlag(context, "payload");
35
+ if (text === undefined)
36
+ return undefined;
37
+ let parsed;
38
+ try {
39
+ parsed = JSON.parse(text);
40
+ }
41
+ catch {
42
+ throw usageError(context, "`--payload` must be valid JSON.");
43
+ }
44
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
45
+ throw usageError(context, "`--payload` must be a JSON object.");
46
+ }
47
+ return parsed;
48
+ }
49
+ /** The result, discriminated by kind — the three known arms, then the open one. */
50
+ function renderResult(env, styles) {
51
+ if (isActionRun(env)) {
52
+ return `${styles.bold("action")}\n${JSON.stringify(env.value, null, 2)}`;
53
+ }
54
+ if (isFunctionRun(env)) {
55
+ return `${styles.bold("function")}\n${JSON.stringify(env.output, null, 2)}`;
56
+ }
57
+ if (isWorkflowRun(env)) {
58
+ return `${styles.bold("workflow")} — ${env.runId} (${env.status})\n` +
59
+ styles.dim("use `w6w workflows run " + env.runId + " --wait` to follow it");
60
+ }
61
+ // The open fourth arm: a kind this build does not know. Shown, not raised.
62
+ return `${styles.dim(`kind: ${env.kind} (not recognized by this build)`)}\n` +
63
+ JSON.stringify(env, null, 2);
64
+ }
65
+ const run = async (context) => {
66
+ const urn = argument(context, 0, "a URN — conn_…, wf_…, fn_… or ep_… (see: `w6w connections list`, `w6w workflows list`)");
67
+ noExtraArguments(context, 1);
68
+ const result = await context.client().run({
69
+ urn,
70
+ action: textFlag(context, "action"),
71
+ payload: payload(context),
72
+ });
73
+ context.out.emit(result, (styles) => renderResult(result, styles));
74
+ };
75
+ export const RUN_COMMANDS = {
76
+ "run": run,
77
+ };
78
+ //# sourceMappingURL=run.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/commands/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAoB,MAAM,UAAU,CAAC;AAEvF,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE/E;;;;;;;;GAQG;AACH,SAAS,OAAO,CAAC,OAAuB;IACtC,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC1C,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACzC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,UAAU,CAAC,OAAO,EAAE,iCAAiC,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,UAAU,CAAC,OAAO,EAAE,oCAAoC,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,MAAiC,CAAC;AAC3C,CAAC;AAED,mFAAmF;AACnF,SAAS,YAAY,CAAC,GAAgB,EAAE,MAAc;IACpD,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;IAC3E,CAAC;IACD,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;IAC9E,CAAC;IACD,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,KAAK,KAAK,GAAG,CAAC,MAAM,KAAK;YAClE,MAAM,CAAC,GAAG,CAAC,yBAAyB,GAAG,GAAG,CAAC,KAAK,GAAG,uBAAuB,CAAC,CAAC;IAChF,CAAC;IACD,2EAA2E;IAC3E,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,GAAG,CAAC,IAAI,iCAAiC,CAAC,IAAI;QAC1E,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,GAAG,GAAmB,KAAK,EAAE,OAAO,EAAE,EAAE;IAC5C,MAAM,GAAG,GAAG,QAAQ,CAClB,OAAO,EACP,CAAC,EACD,wFAAwF,CACzF,CAAC;IACF,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC;QACxC,GAAG;QACH,MAAM,EAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;QACnC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC;KAC1B,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AACrE,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAoB;IAC3C,KAAK,EAAE,GAAG;CACX,CAAC"}
@@ -0,0 +1,117 @@
1
+ /**
2
+ * The vocabulary every command handler shares: reading its own arguments,
3
+ * failing as a usage error, and rendering.
4
+ *
5
+ * It exists because the alternative is worse in both directions. Copying these
6
+ * accessors into each command group gives four spellings of "was this flag
7
+ * given?" — and that question is exactly the one D2 turns on, where a wrong
8
+ * answer silently rewrites a field the user never mentioned. Putting them in
9
+ * `./index.ts` instead would make the registry — the file every command group
10
+ * appends itself to — also the file every group edits, which is how a merge
11
+ * point becomes a merge conflict.
12
+ *
13
+ * Two rules hold everywhere below:
14
+ *
15
+ * 1. **A usage error is thrown, never printed.** `main()` reports it on stderr
16
+ * once and maps it through `src/exit.ts` to exit `1`; a handler that wrote
17
+ * its own message would be a second error path to keep in sync.
18
+ * 2. **Presence is `!== undefined`, never truthiness.** `--description ""` is a
19
+ * flag the user supplied, and it means "clear the description" — a `if
20
+ * (value)` test would drop it on the floor.
21
+ *
22
+ * @module
23
+ */
24
+ import type { CommandContext } from "../../mod.ts";
25
+ import type { Styles } from "../output.ts";
26
+ /**
27
+ * A bad invocation, phrased for the person who typed it.
28
+ *
29
+ * The usage line is the contract's own `naming.cli` spelling rather than a
30
+ * restatement of it, so the thing a user is told to type cannot drift from the
31
+ * thing the surface contract declares.
32
+ *
33
+ * It is a plain `Error` on purpose: `src/exit.ts` maps every non-`ApiError`
34
+ * throw to the usage code, because anything that is not an `ApiError` never
35
+ * reached the server. A bespoke class would add a name to the stack trace and
36
+ * change nothing about the exit code.
37
+ *
38
+ * @param context - The command being run.
39
+ * @param problem - What was wrong, as a sentence.
40
+ * @returns The error to throw.
41
+ */
42
+ export declare function usageError(context: CommandContext, problem: string): Error;
43
+ /**
44
+ * One positional argument, required.
45
+ *
46
+ * An **empty** argument counts as missing. That is an argument-presence rule and
47
+ * not a value policy: the server accepts no empty key, name or id, so refusing
48
+ * `""` here makes nothing unreachable — unlike a key such as `".."`, which is
49
+ * legitimately creatable and is therefore never rejected client-side (see
50
+ * `documents get-by-key`).
51
+ *
52
+ * @param context - The command being run.
53
+ * @param index - Position of the argument, after the command path.
54
+ * @param what - What is expected, e.g. ``"a document id (see: `w6w documents list`)"``.
55
+ * @returns The argument.
56
+ * @throws {Error} A usage error when it is absent or empty.
57
+ */
58
+ export declare function argument(context: CommandContext, index: number, what: string): string;
59
+ /**
60
+ * Reject arguments the command does not take.
61
+ *
62
+ * Silence here is how a typo becomes a surprise: `w6w documents get doc_1 doc_2`
63
+ * would fetch the first id and ignore the second, and `w6w vars list --project`
64
+ * escaped past `--` would list everything as though the scope had been applied.
65
+ *
66
+ * @param context - The command being run.
67
+ * @param expected - How many positional arguments the command takes.
68
+ * @throws {Error} A usage error naming the first extra argument.
69
+ */
70
+ export declare function noExtraArguments(context: CommandContext, expected: number): void;
71
+ /**
72
+ * One flag's value, or `undefined` where the flag was not given.
73
+ *
74
+ * The distinction is the whole of D2: an absent flag must leave the server's
75
+ * field alone, and only a flag the user actually typed may change it. Callers
76
+ * therefore test `!== undefined` and never truthiness.
77
+ *
78
+ * @param context - The command being run.
79
+ * @param name - The flag's camelCased key, e.g. `"project"`, `"description"`.
80
+ * @returns The value as typed, or `undefined`.
81
+ */
82
+ export declare function textFlag(context: CommandContext, name: string): string | undefined;
83
+ /**
84
+ * One flag's value, required.
85
+ *
86
+ * @param context - The command being run.
87
+ * @param name - The flag's camelCased key.
88
+ * @param display - How the flag is spelled in help, e.g. `"--content <text>"`.
89
+ * @returns The value as typed.
90
+ * @throws {Error} A usage error when the flag is absent.
91
+ */
92
+ export declare function requiredFlag(context: CommandContext, name: string, display: string): string;
93
+ /**
94
+ * Render rows as aligned columns under a dimmed header.
95
+ *
96
+ * The last column is never padded, so a value that runs long widens nothing and
97
+ * a copied line carries no trailing whitespace.
98
+ *
99
+ * @param header - Column titles.
100
+ * @param rows - The rows, each the same length as `header`.
101
+ * @param styles - The invocation's decorations; plain text when colour is off.
102
+ * @returns The table, newline-separated.
103
+ */
104
+ export declare function table(header: string[], rows: string[][], styles: Styles): string;
105
+ /**
106
+ * A one-line preview of an opaque value, for a table cell.
107
+ *
108
+ * JSON rather than the value's own text: a variable's value may be a string, a
109
+ * number, a boolean or a whole document, and `hello` versus `"hello"` is the
110
+ * difference between a `string` variable and a `json` one holding a string.
111
+ *
112
+ * @param value - The value, straight off the wire.
113
+ * @param width - Maximum characters before an ellipsis.
114
+ * @returns The preview.
115
+ */
116
+ export declare function preview(value: unknown, width?: number): string;
117
+ //# sourceMappingURL=shared.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/commands/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAO3C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAE1E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMrF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAUhF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAM3F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAShF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAK,GAAG,MAAM,CAG1D"}