@clifn/core 0.1.0 → 0.2.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.
- package/README.md +32 -16
- package/dist/client.d.ts +2 -0
- package/dist/client.js +1 -1
- package/dist/credentials.js +46 -14
- package/package.json +10 -5
package/README.md
CHANGED
|
@@ -36,7 +36,6 @@ import { createCredentialStore } from "@clifn/core/credentials";
|
|
|
36
36
|
import { createProjectConfig } from "@clifn/core/config";
|
|
37
37
|
import { createApiClient } from "@clifn/core/client";
|
|
38
38
|
import { readJsonStdin, writeJsonStdout } from "@clifn/core/stdio";
|
|
39
|
-
import { ui } from "@clifn/core/ui";
|
|
40
39
|
|
|
41
40
|
const credentials = createCredentialStore();
|
|
42
41
|
const config = createProjectConfig();
|
|
@@ -49,7 +48,7 @@ const api = createApiClient({
|
|
|
49
48
|
});
|
|
50
49
|
|
|
51
50
|
const input = await readJsonStdin<{ command: string }>();
|
|
52
|
-
|
|
51
|
+
process.stderr.write(`running command: ${input.command}\n`);
|
|
53
52
|
const result = await api.post("/runs", input);
|
|
54
53
|
writeJsonStdout(result.data);
|
|
55
54
|
```
|
|
@@ -98,8 +97,8 @@ process.exitCode = exitCode;
|
|
|
98
97
|
|
|
99
98
|
The current repository already uses all three parser styles:
|
|
100
99
|
|
|
101
|
-
- `
|
|
102
|
-
- `apifn/cli`
|
|
100
|
+
- `hostfn/cli`, `plugfn/cli`, and `extfn/cli` use `commander`
|
|
101
|
+
- `apifn/cli` uses `cac`
|
|
103
102
|
- `datafn/cli` uses raw `node:util.parseArgs`
|
|
104
103
|
|
|
105
104
|
The parser canaries under `clifn/core/tests/fixtures/*` prove that `runAction()` and the shared output service work in each style without adding parser libraries to `clifn` runtime dependencies.
|
|
@@ -119,7 +118,7 @@ program
|
|
|
119
118
|
.action(async (options, command) => {
|
|
120
119
|
const globals = command.parent?.opts() ?? {};
|
|
121
120
|
|
|
122
|
-
|
|
121
|
+
process.exitCode = await runAction(
|
|
123
122
|
async ({ name }, ctx) => {
|
|
124
123
|
ctx.output.info(`hello ${name}`);
|
|
125
124
|
},
|
|
@@ -129,6 +128,8 @@ program
|
|
|
129
128
|
}
|
|
130
129
|
);
|
|
131
130
|
});
|
|
131
|
+
|
|
132
|
+
await program.parseAsync(process.argv);
|
|
132
133
|
```
|
|
133
134
|
|
|
134
135
|
### `cac`
|
|
@@ -143,8 +144,8 @@ cli.option("--json", "Emit machine-readable output");
|
|
|
143
144
|
cli
|
|
144
145
|
.command("greet")
|
|
145
146
|
.option("--name <name>", "Name to greet")
|
|
146
|
-
.action((options) =>
|
|
147
|
-
runAction(
|
|
147
|
+
.action(async (options) => {
|
|
148
|
+
process.exitCode = await runAction(
|
|
148
149
|
async ({ name }, ctx) => {
|
|
149
150
|
return {
|
|
150
151
|
data: {
|
|
@@ -157,8 +158,11 @@ cli
|
|
|
157
158
|
{
|
|
158
159
|
mode: options.json ? "json" : "text",
|
|
159
160
|
}
|
|
160
|
-
)
|
|
161
|
-
);
|
|
161
|
+
);
|
|
162
|
+
});
|
|
163
|
+
|
|
164
|
+
cli.parse(process.argv, { run: false });
|
|
165
|
+
await cli.runMatchedCommand();
|
|
162
166
|
```
|
|
163
167
|
|
|
164
168
|
### `node:util.parseArgs`
|
|
@@ -176,7 +180,7 @@ const { values, positionals } = parseArgs({
|
|
|
176
180
|
});
|
|
177
181
|
|
|
178
182
|
if (positionals[0] === "greet") {
|
|
179
|
-
await runAction(
|
|
183
|
+
process.exitCode = await runAction(
|
|
180
184
|
async ({ name }, ctx) => {
|
|
181
185
|
ctx.output.info(`hello ${name}`);
|
|
182
186
|
},
|
|
@@ -267,8 +271,8 @@ These module entrypoints are the generic surface that repository CLIs can share:
|
|
|
267
271
|
`clifn` is the shared home for generic CLI-builder concerns that appear across existing repository CLIs such as:
|
|
268
272
|
|
|
269
273
|
- `packages/cli` and `apifn/cli` for config loading patterns
|
|
270
|
-
- `hostfn/cli`, `
|
|
271
|
-
- `
|
|
274
|
+
- `hostfn/cli`, `plugfn/cli`, and `apifn/cli` for output and command-runner patterns
|
|
275
|
+
- `plugfn/cli` and `mcpfn/cli` for structured diagnostics and test/reporting surfaces
|
|
272
276
|
|
|
273
277
|
Responsibilities that belong in `clifn`:
|
|
274
278
|
|
|
@@ -321,15 +325,17 @@ Responsibilities that stay in the owning CLI:
|
|
|
321
325
|
- Product-owned concerns that stay local:
|
|
322
326
|
- deployment workflows, SSH/server orchestration, runtime adapters, and host-specific validation
|
|
323
327
|
|
|
324
|
-
### `
|
|
328
|
+
### `plugfn/cli`
|
|
325
329
|
|
|
326
330
|
- Repeated pattern today:
|
|
327
|
-
- text/json rendering
|
|
331
|
+
- text/json rendering in `plugfn/cli/src/commands/runtime.ts`
|
|
332
|
+
- structured diagnostics in `plugfn/cli/src/commands/test.ts`
|
|
328
333
|
- `clifn` adoption target:
|
|
329
334
|
- `@clifn/core/output` for generic mode switching and transport
|
|
330
|
-
-
|
|
335
|
+
- `@clifn/core/diagnostics` for stable diagnostic formatting
|
|
336
|
+
- keep domain-specific formatters local where they encode provider/runtime semantics
|
|
331
337
|
- Product-owned concerns that stay local:
|
|
332
|
-
-
|
|
338
|
+
- provider diagnostics, webhook fixtures, and integration-specific data shapes
|
|
333
339
|
|
|
334
340
|
### extfn adoption contract
|
|
335
341
|
|
|
@@ -381,3 +387,13 @@ If `extfn/cli` needs a generic capability that is not yet exported by `clifn`, t
|
|
|
381
387
|
- `@clifn/core/prompt`
|
|
382
388
|
|
|
383
389
|
Use these public subpaths directly; do not import from internal `dist/*` paths.
|
|
390
|
+
|
|
391
|
+
## Application credentials and safe retry defaults
|
|
392
|
+
|
|
393
|
+
Pass an explicit path to `createCredentialStore` for each product (for example its own config directory); the legacy default remains Conduct-specific. Writes hold an exclusive sibling `.lock`, write and fsync a unique mode-0600 temporary file, then rename it atomically. Concurrent writes fail with `CLIFN_CREDENTIAL_STORE_BUSY` rather than losing updates. After a process crash, stop all writers and inspect/remove only its stale lock before retrying. Symlink credential files are rejected. Filesystem permissions are a fallback, not encryption or an OS keychain.
|
|
394
|
+
|
|
395
|
+
The synchronous `CredentialStore` interface is injectable into `createApiClient`. A consumer keychain adapter should use a product-specific service name and profile account, store each complete `{backend,key}` value atomically, and expose only profile names in diagnostics. An asynchronous OS keychain can be loaded at CLI startup into a short-lived in-memory implementation; persist changes through the keychain before reporting success. Never serialize keychain values to a config file as an implicit fallback.
|
|
396
|
+
|
|
397
|
+
Only GET requests retry by default. `request({ ..., retrySafe: true })` opts in when the server guarantees idempotency for that operation; it does not manufacture such a guarantee. Non-replayable request bodies are not retried. A timed-out write may already have succeeded and must be reconciled.
|
|
398
|
+
|
|
399
|
+
Executable naming belongs to the consumer package. Rex's `rex-agent` package should declare both `rex` and `rex-agent` bins targeting the same entrypoint, detect an existing `rex` command and document the fallback. Do not use forced installation to overwrite another package's executable.
|
package/dist/client.d.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { type CredentialStore } from "./credentials.js";
|
|
2
2
|
export interface ApiRequestOptions {
|
|
3
|
+
/** Opt in only when the server guarantees idempotency for this operation. */
|
|
4
|
+
retrySafe?: boolean;
|
|
3
5
|
method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
|
|
4
6
|
path: string;
|
|
5
7
|
query?: Record<string, string | number | boolean | undefined>;
|
package/dist/client.js
CHANGED
|
@@ -119,7 +119,7 @@ export function createApiClient(config) {
|
|
|
119
119
|
const message = error instanceof Error ? error.message : "invalid request url";
|
|
120
120
|
throw new HttpRequestError(auth.baseUrl, message, error);
|
|
121
121
|
}
|
|
122
|
-
const maxRetries = isOneShotBody(options.body) ? 0 : retries;
|
|
122
|
+
const maxRetries = isOneShotBody(options.body) || (method !== "GET" && options.retrySafe !== true) ? 0 : retries;
|
|
123
123
|
for (let attempt = 0;; attempt += 1) {
|
|
124
124
|
const controller = new AbortController();
|
|
125
125
|
const timeout = setTimeout(() => controller.abort(), timeoutMs);
|
package/dist/credentials.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
1
|
+
import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, openSync, closeSync, fsyncSync, renameSync, unlinkSync, lstatSync } from "node:fs";
|
|
2
|
+
import { randomUUID } from "node:crypto";
|
|
2
3
|
import { homedir } from "node:os";
|
|
3
4
|
import { dirname, join } from "node:path";
|
|
4
5
|
import ini from "ini";
|
|
@@ -16,11 +17,13 @@ export class MissingProfileError extends Error {
|
|
|
16
17
|
const DEFAULT_CREDENTIALS_PATH = join(homedir(), ".conduct", "credentials");
|
|
17
18
|
function readProfiles(path) {
|
|
18
19
|
if (!existsSync(path)) {
|
|
19
|
-
return
|
|
20
|
+
return Object.create(null);
|
|
20
21
|
}
|
|
22
|
+
if (lstatSync(path).isSymbolicLink())
|
|
23
|
+
throw new Error("CLIFN_CREDENTIAL_SYMLINK");
|
|
21
24
|
const raw = readFileSync(path, "utf8");
|
|
22
25
|
const parsed = ini.parse(raw);
|
|
23
|
-
const out =
|
|
26
|
+
const out = Object.create(null);
|
|
24
27
|
for (const [name, value] of Object.entries(parsed)) {
|
|
25
28
|
if (typeof value !== "object" || value === null) {
|
|
26
29
|
continue;
|
|
@@ -40,8 +43,42 @@ function writeProfiles(path, profiles) {
|
|
|
40
43
|
mkdirSync(directory, { recursive: true, mode: 0o700 });
|
|
41
44
|
chmodSync(directory, 0o700);
|
|
42
45
|
const serialized = ini.stringify(profiles);
|
|
43
|
-
|
|
44
|
-
|
|
46
|
+
const temporary = `${path}.${randomUUID()}.tmp`;
|
|
47
|
+
let fd;
|
|
48
|
+
try {
|
|
49
|
+
fd = openSync(temporary, 'wx', 0o600);
|
|
50
|
+
writeFileSync(fd, serialized, 'utf8');
|
|
51
|
+
fsyncSync(fd);
|
|
52
|
+
closeSync(fd);
|
|
53
|
+
fd = undefined;
|
|
54
|
+
renameSync(temporary, path);
|
|
55
|
+
}
|
|
56
|
+
finally {
|
|
57
|
+
if (fd !== undefined)
|
|
58
|
+
closeSync(fd);
|
|
59
|
+
if (existsSync(temporary))
|
|
60
|
+
unlinkSync(temporary);
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
/** Exclusive read-modify-write lock. A crashed writer leaves a detectable lock, never lost updates. */
|
|
64
|
+
function mutateProfiles(path, change) {
|
|
65
|
+
mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
|
|
66
|
+
let fd;
|
|
67
|
+
try {
|
|
68
|
+
fd = openSync(`${path}.lock`, 'wx', 0o600);
|
|
69
|
+
}
|
|
70
|
+
catch (cause) {
|
|
71
|
+
throw new Error('CLIFN_CREDENTIAL_STORE_BUSY', { cause });
|
|
72
|
+
}
|
|
73
|
+
try {
|
|
74
|
+
const profiles = readProfiles(path);
|
|
75
|
+
change(profiles);
|
|
76
|
+
writeProfiles(path, profiles);
|
|
77
|
+
}
|
|
78
|
+
finally {
|
|
79
|
+
closeSync(fd);
|
|
80
|
+
unlinkSync(`${path}.lock`);
|
|
81
|
+
}
|
|
45
82
|
}
|
|
46
83
|
export function createCredentialStore(path = DEFAULT_CREDENTIALS_PATH) {
|
|
47
84
|
return {
|
|
@@ -55,9 +92,9 @@ export function createCredentialStore(path = DEFAULT_CREDENTIALS_PATH) {
|
|
|
55
92
|
return profile;
|
|
56
93
|
},
|
|
57
94
|
setProfile(name, profile) {
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
95
|
+
if (!name || ["__proto__", "constructor", "prototype"].includes(name))
|
|
96
|
+
throw new Error("CLIFN_INVALID_PROFILE_NAME");
|
|
97
|
+
mutateProfiles(path, profiles => { Object.defineProperty(profiles, name, { value: profile, enumerable: true, configurable: true, writable: true }); });
|
|
61
98
|
},
|
|
62
99
|
hasProfile(name) {
|
|
63
100
|
const profiles = readProfiles(path);
|
|
@@ -68,12 +105,7 @@ export function createCredentialStore(path = DEFAULT_CREDENTIALS_PATH) {
|
|
|
68
105
|
return Object.keys(profiles);
|
|
69
106
|
},
|
|
70
107
|
removeProfile(name) {
|
|
71
|
-
|
|
72
|
-
if (!profiles[name]) {
|
|
73
|
-
return;
|
|
74
|
-
}
|
|
75
|
-
delete profiles[name];
|
|
76
|
-
writeProfiles(path, profiles);
|
|
108
|
+
mutateProfiles(path, profiles => { delete profiles[name]; });
|
|
77
109
|
},
|
|
78
110
|
};
|
|
79
111
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clifn/core",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Reusable CLI primitives runtime for the Superfunctions ecosystem",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -63,6 +63,9 @@
|
|
|
63
63
|
"import": "./dist/prompt.js"
|
|
64
64
|
}
|
|
65
65
|
},
|
|
66
|
+
"engines": {
|
|
67
|
+
"node": ">=20"
|
|
68
|
+
},
|
|
66
69
|
"files": [
|
|
67
70
|
"dist",
|
|
68
71
|
"README.md"
|
|
@@ -70,7 +73,8 @@
|
|
|
70
73
|
"scripts": {
|
|
71
74
|
"build": "tsc",
|
|
72
75
|
"dev": "tsc --watch",
|
|
73
|
-
"
|
|
76
|
+
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
77
|
+
"test": "vitest run",
|
|
74
78
|
"test:watch": "vitest --watch",
|
|
75
79
|
"lint": "echo 'lint not configured'",
|
|
76
80
|
"clean": "rm -rf dist"
|
|
@@ -89,7 +93,7 @@
|
|
|
89
93
|
"author": "21n",
|
|
90
94
|
"license": "MIT",
|
|
91
95
|
"dependencies": {
|
|
92
|
-
"ini": "^
|
|
96
|
+
"ini": "^4.1.3",
|
|
93
97
|
"jiti": "^2.4.2"
|
|
94
98
|
},
|
|
95
99
|
"devDependencies": {
|
|
@@ -102,7 +106,7 @@
|
|
|
102
106
|
},
|
|
103
107
|
"repository": {
|
|
104
108
|
"type": "git",
|
|
105
|
-
"url": "git+https://github.com/21nCo/
|
|
109
|
+
"url": "git+https://github.com/21nCo/superfunctions.git",
|
|
106
110
|
"directory": "clifn/core"
|
|
107
111
|
},
|
|
108
112
|
"superfunctionsPhasePlan": {
|
|
@@ -116,5 +120,6 @@
|
|
|
116
120
|
},
|
|
117
121
|
"publishConfig": {
|
|
118
122
|
"access": "public"
|
|
119
|
-
}
|
|
123
|
+
},
|
|
124
|
+
"gitHead": "1192477184fb1f537bbbce3c9fb574ac81714053"
|
|
120
125
|
}
|