@clifn/core 0.1.0 → 0.1.1

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
@@ -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
- ui.info(`running command: ${input.command}`);
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
- - `contentfn/cli` and `hostfn/cli` use `commander`
102
- - `apifn/cli` and `docsfn/cli` use `cac`
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
- return runAction(
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`, `recfn/cli`, and `apifn/cli` for output and command-runner patterns
271
- - `docsfn/cli` and `plugfn/cli` for structured diagnostics and test/reporting surfaces
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
- ### `recfn/cli`
328
+ ### `plugfn/cli`
325
329
 
326
330
  - Repeated pattern today:
327
- - text/json rendering and table-like formatting in `recfn/cli/src/output.ts`
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
- - keep domain-specific formatters local where they encode recording/bot semantics
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
- - recording analytics formatting, transcript search semantics, and recorder-specific data shapes
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);
@@ -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
- writeFileSync(path, serialized, { encoding: "utf8", mode: 0o600 });
44
- chmodSync(path, 0o600);
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
- const profiles = readProfiles(path);
59
- profiles[name] = profile;
60
- writeProfiles(path, profiles);
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
- const profiles = readProfiles(path);
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.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Reusable CLI primitives runtime for the Superfunctions ecosystem",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -102,7 +102,7 @@
102
102
  },
103
103
  "repository": {
104
104
  "type": "git",
105
- "url": "git+https://github.com/21nCo/super-functions.git",
105
+ "url": "git+https://github.com/21nCo/superfunctions.git",
106
106
  "directory": "clifn/core"
107
107
  },
108
108
  "superfunctionsPhasePlan": {
@@ -116,5 +116,6 @@
116
116
  },
117
117
  "publishConfig": {
118
118
  "access": "public"
119
- }
119
+ },
120
+ "gitHead": "699d9d09932199d660333c57fe7bc646492ea3bf"
120
121
  }