@solidactions/cli 3.15.0 → 3.16.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 CHANGED
@@ -75,8 +75,22 @@ instructions. Then ask: “Which SolidActions skills are installed, and which
75
75
  one should you use to deploy this workflow?” The answer should identify the
76
76
  installed skills and select `solidactions-deploy-and-config` for deployment.
77
77
 
78
- For an existing project, install or refresh the same tooling with
79
- `solidactions ai init --claude` or `solidactions ai init --agents`.
78
+ For an existing project, install the same tooling with
79
+ `solidactions ai init --claude` or `solidactions ai init --agents`. Installed
80
+ skill directories carry a `.solidactions-version` stamp; when the CLI reports
81
+ that stamp is stale, run `solidactions ai init --update` to refresh the existing
82
+ helper target.
83
+
84
+ ### Agent freshness notices
85
+
86
+ The CLI may print four kinds of one-line `AGENT NOTE` notices to stderr: a cached
87
+ daily outdated-CLI notice, a missing- or stale-skills prompt, and a notice in a
88
+ Claude Cowork sandbox that its project skills are not auto-loaded. The npm
89
+ registry refresh runs detached and silently; normal invocations read only its
90
+ daily cache. These notices never alter stdout, including `--json` output.
91
+
92
+ Set `SOLIDACTIONS_NO_AGENT_NUDGES=1` to suppress all four notices and the
93
+ background update refresh.
80
94
 
81
95
  ## Database CLI
82
96
 
@@ -464,7 +478,7 @@ You do **not** need `--overwrite` to keep an edited file whose doc was deleted o
464
478
 
465
479
  | Command | Key Flags | Description |
466
480
  |---------|-----------|-------------|
467
- | `ai init` | `--claude`, `--agents` | Install AI skills and SDK reference into an **existing** project (use `init` for new projects) |
481
+ | `ai init` | `--claude`, `--agents`, `--update` | Install or refresh AI skills and SDK reference in an **existing** project (use `init` for new projects) |
468
482
  | `ai examples [names...]` | `--all`, `--overwrite` | Install example workflows |
469
483
 
470
484
  `ai init` installs five auto-activating SolidActions skills and a
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schema_version": 1,
3
3
  "cli_name": "solidactions",
4
- "cli_version": "3.15.0",
4
+ "cli_version": "3.16.0",
5
5
  "global_options": [
6
6
  {
7
7
  "flags": "-V, --version",
@@ -4181,6 +4181,18 @@
4181
4181
  "negated": false,
4182
4182
  "hidden": false
4183
4183
  },
4184
+ {
4185
+ "flags": "--update",
4186
+ "long": "--update",
4187
+ "short": null,
4188
+ "description": "Refresh the installed helper target and its version-stamped skills",
4189
+ "required": false,
4190
+ "value_required": false,
4191
+ "value_optional": false,
4192
+ "variadic": false,
4193
+ "negated": false,
4194
+ "hidden": false
4195
+ },
4184
4196
  {
4185
4197
  "flags": "-h, --help",
4186
4198
  "long": "--help",
@@ -34,6 +34,14 @@ async function resolveAiHelperTarget(options = {}) {
34
34
  if (options.agents) {
35
35
  return 'AGENTS.md';
36
36
  }
37
+ if (options.update) {
38
+ const installed = (0, skills_1.findInstalledSkillDirs)(process.cwd());
39
+ const stale = installed.filter((dir) => !(0, skills_1.isSkillDirCurrent)(dir));
40
+ const candidates = stale.length > 0 ? stale : installed;
41
+ if (candidates.length === 1) {
42
+ return candidates[0].includes(`${path_1.default.sep}.agents${path_1.default.sep}`) ? 'AGENTS.md' : 'CLAUDE.md';
43
+ }
44
+ }
37
45
  if (process.stdin.isTTY) {
38
46
  const response = await (0, prompts_1.default)({
39
47
  type: 'select',
@@ -36,6 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
36
36
  return (mod && mod.__esModule) ? mod : { "default": mod };
37
37
  };
38
38
  Object.defineProperty(exports, "__esModule", { value: true });
39
+ exports.isUnresolvedDatabaseDeclaration = isUnresolvedDatabaseDeclaration;
39
40
  exports.buildSaApiClient = buildSaApiClient;
40
41
  exports.assertProjectLocalConfig = assertProjectLocalConfig;
41
42
  exports.resolveProjectSlug = resolveProjectSlug;
@@ -51,6 +52,38 @@ const js_yaml_1 = __importDefault(require("js-yaml"));
51
52
  const crypto_1 = require("crypto");
52
53
  const module_1 = require("module");
53
54
  const config_1 = require("../utils/config");
55
+ /**
56
+ * Does this mapping declare a database in `solidactions.yaml` that the platform
57
+ * could not find?
58
+ *
59
+ * A typo'd or not-yet-created database name never becomes a
60
+ * `workspace_database` mapping at all — the platform records the YAML
61
+ * declaration and flags `yaml_default_not_found`, leaving `source_type` as an
62
+ * ordinary valueless var. Without this discriminator such a mapping falls into
63
+ * the generic "declared var had no value in this env and was skipped" bucket,
64
+ * which tells the user nothing about the actual cause: the name in their YAML
65
+ * does not match any database in the workspace.
66
+ *
67
+ * Mirrors the discriminator `env list` already uses to render
68
+ * `<name> (not configured)`, so the three surfaces agree on the shape.
69
+ */
70
+ function isUnresolvedDatabaseDeclaration(pv) {
71
+ return pv.source_type !== 'workspace_database'
72
+ && pv.yaml_default_not_found === true
73
+ && typeof pv.yaml_default_workspace_database_name === 'string'
74
+ && pv.yaml_default_workspace_database_name.length > 0;
75
+ }
76
+ /**
77
+ * Control-plane refusal codes that mean "you may not mint a WRITE credential
78
+ * here", as opposed to "this database cannot be reached at all". Only these
79
+ * downgrade a `dev --env` mint from write to read-only.
80
+ */
81
+ const WRITE_AUTHORITY_REFUSAL_CODES = new Set([
82
+ 'token_missing_ability', // the CLI token carries databases:read but not databases:edit
83
+ 'writes_exhausted', // WriteFuse: monthly org write budget spent
84
+ 'storage_exhausted', // WriteFuse: org over its storage pool
85
+ 'forbidden', // workspace role may read databases but not use/build them
86
+ ]);
54
87
  /**
55
88
  * Build the production `SaApiClient`: fetches `variable-mappings` with
56
89
  * `reveal=true` so secret values are populated on `ctx.vars`. When the token
@@ -79,6 +112,32 @@ function buildSaApiClient(config, projectSlug) {
79
112
  throw e;
80
113
  }
81
114
  },
115
+ async resolveDatabaseCredential(databaseName) {
116
+ const { requestDatabaseAccess } = await Promise.resolve().then(() => __importStar(require('../utils/database-data-plane')));
117
+ // Parity with the platform's RuntimeEnvBuilder, whose authorization
118
+ // is WriteFuse::authorizationFor() — full-access unless the fuse has
119
+ // degraded. So ask for `write` first and settle for `read` only when
120
+ // the refusal is specifically about WRITE authority. A refusal about
121
+ // the DATABASE (missing, not ready, plan-denied, reads exhausted,
122
+ // rate-limited) must NOT be retried as a read: the read would fail
123
+ // the same way, and the second call burns another mint against the
124
+ // 20/min limit while replacing the accurate error with a vaguer one.
125
+ let access;
126
+ try {
127
+ access = await requestDatabaseAccess(config, databaseName, 'write');
128
+ }
129
+ catch (e) {
130
+ if (!WRITE_AUTHORITY_REFUSAL_CODES.has(e?.code))
131
+ throw e;
132
+ access = await requestDatabaseAccess(config, databaseName, 'read');
133
+ }
134
+ return {
135
+ url: access.url,
136
+ token: access.token,
137
+ name: databaseName,
138
+ read_only: access.mode === 'read',
139
+ };
140
+ },
82
141
  };
83
142
  return client;
84
143
  }
@@ -417,6 +476,8 @@ async function runDev(opts) {
417
476
  let connectionCount = 0;
418
477
  let droppedCount = 0;
419
478
  let droppedSecretCount = 0;
479
+ const databaseMappings = [];
480
+ let unresolvedDatabaseCount = 0;
420
481
  for (const pv of platformVars) {
421
482
  if (pv.source_type === 'oauth_connection' && pv.proxy_url && pv.proxy_token && pv.connection_key) {
422
483
  vars[pv.env_name] = {
@@ -426,6 +487,21 @@ async function runDev(opts) {
426
487
  };
427
488
  connectionCount++;
428
489
  }
490
+ else if (isUnresolvedDatabaseDeclaration(pv)) {
491
+ // Named, never counted as a generic skipped var (#140 review R1).
492
+ err(`${pv.env_name}: mapped database not found — check the database name in `
493
+ + `solidactions.yaml: no database named '${pv.yaml_default_workspace_database_name}' `
494
+ + 'exists in this workspace. `solidactions database list` shows what does; '
495
+ + '`solidactions database create ' + pv.yaml_default_workspace_database_name + '` creates it.');
496
+ unresolvedDatabaseCount++;
497
+ }
498
+ else if (pv.source_type === 'workspace_database') {
499
+ // Never counted as dropped: a database mapping ALWAYS arrives with a
500
+ // null resolved_value (the mappings endpoint deliberately does not
501
+ // carry credentials), so counting it here would report a healthy
502
+ // mapping as "had no value in this env and was skipped" (#140).
503
+ databaseMappings.push(pv);
504
+ }
429
505
  else if (pv.resolved_value != null) {
430
506
  vars[pv.env_name] = pv.resolved_value;
431
507
  }
@@ -436,6 +512,50 @@ async function runDev(opts) {
436
512
  droppedCount++;
437
513
  }
438
514
  }
515
+ // 3b. Resolve mapped workspace databases onto ctx.vars as {@link
516
+ // DevDatabaseVar} — the same object a DEPLOYED workflow reads. The
517
+ // platform injects RuntimeEnvBuilder's `{url, token, name, read_only}`
518
+ // JSON string into a sandbox's env and the SDK's context-adapter parses
519
+ // it; `dev` builds ctx.vars itself and never runs that adapter, so the
520
+ // conversion happens here instead (see DevDatabaseVar).
521
+ //
522
+ // The credentials are short-TTL (the control plane's 600s floor) and
523
+ // live only in this process's memory: they reach the workflow through
524
+ // ctx.vars and are never written to a file. `env pull` deliberately does
525
+ // NOT resolve them for exactly that reason — it writes to disk.
526
+ let databaseCount = 0;
527
+ for (const pv of databaseMappings) {
528
+ const dbName = pv.workspace_database_name;
529
+ if (pv.workspace_database_broken || !dbName) {
530
+ // NOT `env map` — that maps GLOBAL VARIABLES and has no --database
531
+ // flag. A project's database mapping is a solidactions.yaml
532
+ // declaration synced by `project deploy`.
533
+ err(`${pv.env_name}: mapped database no longer exists. Point it at a live database in `
534
+ + 'solidactions.yaml (`- ' + pv.env_name + ':` / ` database: "<name>"`), then re-run '
535
+ + '`solidactions project deploy <project> <path>`. `solidactions database list` shows what exists.');
536
+ continue;
537
+ }
538
+ if (!apiClient.resolveDatabaseCredential) {
539
+ err(`${pv.env_name}: cannot resolve database '${dbName}' — this client cannot mint credentials.`);
540
+ continue;
541
+ }
542
+ try {
543
+ const credential = await apiClient.resolveDatabaseCredential(dbName);
544
+ vars[pv.env_name] = {
545
+ name: credential.name,
546
+ url: credential.url,
547
+ token: credential.token,
548
+ readOnly: credential.read_only,
549
+ };
550
+ databaseCount++;
551
+ if (credential.read_only) {
552
+ err(`${pv.env_name}: database '${dbName}' resolved READ-ONLY — writes (including drizzle-kit migrations) will fail.`);
553
+ }
554
+ }
555
+ catch (e) {
556
+ err(`${pv.env_name}: failed to resolve database '${dbName}': ${e?.message ?? e}`);
557
+ }
558
+ }
439
559
  // 4. Apply overrides, warning on shadows.
440
560
  if (opts.varsOverride) {
441
561
  for (const [key, value] of Object.entries(opts.varsOverride)) {
@@ -449,11 +569,17 @@ async function runDev(opts) {
449
569
  // plain-var count is the number of plain vars actually placed in `vars`
450
570
  // (total keys minus connection entries), never the raw mapping count.
451
571
  if (opts.env) {
452
- const plainVarCount = Object.keys(vars).length - connectionCount;
572
+ const plainVarCount = Object.keys(vars).length - connectionCount - databaseCount;
453
573
  let summary = `Loaded ${plainVarCount} vars + ${connectionCount} connections from ${apiClient.projectSlug} / env ${opts.env}`;
574
+ if (databaseCount > 0) {
575
+ summary += ` + ${databaseCount} ${databaseCount === 1 ? 'database' : 'databases'}`;
576
+ }
454
577
  if (droppedCount > 0) {
455
578
  summary += ` (${droppedCount} declared ${droppedCount === 1 ? 'var' : 'vars'} had no value in this env and ${droppedCount === 1 ? 'was' : 'were'} skipped)`;
456
579
  }
580
+ if (unresolvedDatabaseCount > 0) {
581
+ summary += ` — ${unresolvedDatabaseCount} declared ${unresolvedDatabaseCount === 1 ? 'database was' : 'databases were'} not found in this workspace (see above)`;
582
+ }
457
583
  if (droppedSecretCount > 0) {
458
584
  if (apiClient.revealDenied) {
459
585
  summary += ` — ${droppedSecretCount} secret ${droppedSecretCount === 1 ? 'var' : 'vars'} unavailable: your API key lacks the 'env:reveal' ability. Mint a key with env:reveal, or set a test value with \`solidactions env set\`.`;
@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.devEnvHintLine = devEnvHintLine;
6
7
  exports.envPull = envPull;
7
8
  const fs_1 = __importDefault(require("fs"));
8
9
  const path_1 = __importDefault(require("path"));
@@ -26,6 +27,51 @@ async function confirm(message) {
26
27
  });
27
28
  });
28
29
  }
30
+ /**
31
+ * The copy-pasteable next step a reader of either surface should run (#140).
32
+ *
33
+ * Both the CLI note and the `.env` comment END with this line, with the ACTUAL
34
+ * pulled environment substituted, so whoever hits the missing value can paste
35
+ * one command and go rather than reverse-engineering the flag.
36
+ */
37
+ function devEnvHintLine(environment) {
38
+ return `To run locally with live platform vars + this database: solidactions dev <your-workflow-file> --env ${environment}`;
39
+ }
40
+ /**
41
+ * Is this mapping a workspace database?
42
+ *
43
+ * A database mapping ALWAYS pulls with a null value: the platform deliberately
44
+ * does not resolve database credentials to a file-writing command. Without an
45
+ * explicit branch it lands in the generic `# KEY= (no value configured)` line,
46
+ * where a blank reads as broken or unsupported — the failure this issue exists
47
+ * to fix. The absence is a security posture, and both surfaces must say so.
48
+ */
49
+ function isDatabaseMapping(variable) {
50
+ return variable?.source_type === 'workspace_database';
51
+ }
52
+ /**
53
+ * Does this mapping declare a database in `solidactions.yaml` that the platform
54
+ * could not find?
55
+ *
56
+ * A typo'd or not-yet-created database name never becomes a
57
+ * `workspace_database` mapping — the platform records the YAML declaration and
58
+ * flags `yaml_default_not_found`, leaving `source_type` an ordinary valueless
59
+ * var. Without this branch it renders as `# KEY= (no value configured)`, which
60
+ * hides the real cause: the name in the YAML matches no database in the
61
+ * workspace. Mirrors `env list`'s `<name> (not configured)` discriminator.
62
+ */
63
+ function isUnresolvedDatabaseDeclaration(variable) {
64
+ return variable?.source_type !== 'workspace_database'
65
+ && variable?.yaml_default_not_found === true
66
+ && typeof variable?.yaml_default_workspace_database_name === 'string'
67
+ && variable.yaml_default_workspace_database_name.length > 0;
68
+ }
69
+ /** Best-known display name for a mapped database, however the mapping is bound. */
70
+ function databaseDisplayName(variable) {
71
+ return variable?.workspace_database_name
72
+ || variable?.yaml_default_workspace_database_name
73
+ || 'unknown';
74
+ }
29
75
  async function envPull(projectName, options = {}) {
30
76
  const config = await (0, api_1.requireConfigWithWorkspace)();
31
77
  const environment = options.env || 'dev';
@@ -154,9 +200,40 @@ async function envPull(projectName, options = {}) {
154
200
  lines.push('');
155
201
  let count = 0;
156
202
  let secretCount = 0;
203
+ const databaseVars = [];
204
+ const unresolvedDatabaseVars = [];
157
205
  for (const variable of variables) {
158
206
  const key = variable.env_name;
159
207
  const value = variable.resolved_value ?? variable.value;
208
+ // A YAML-declared database the platform could not find explains the
209
+ // ACTUAL cause in place — a typo'd name is not "no value
210
+ // configured" (#140 review R1).
211
+ if (isUnresolvedDatabaseDeclaration(variable)) {
212
+ const wanted = variable.yaml_default_workspace_database_name;
213
+ lines.push(`# ${key}: mapped database NOT FOUND — check the database name in solidactions.yaml:`);
214
+ lines.push(`# no database named '${wanted}' exists in this workspace.`);
215
+ lines.push(`# \`solidactions database list\` shows what does; \`solidactions database create ${wanted}\` creates it.`);
216
+ // Blank line closes the block: several database variables in a
217
+ // row would otherwise run together as one wall of comments,
218
+ // with no way to see which explanation belongs to which var.
219
+ lines.push('');
220
+ unresolvedDatabaseVars.push({ key, wanted });
221
+ continue;
222
+ }
223
+ // A mapped database explains itself IN PLACE, before the generic
224
+ // no-value branch can render it as a blank (#140).
225
+ if (isDatabaseMapping(variable)) {
226
+ const dbName = databaseDisplayName(variable);
227
+ lines.push(`# ${key}: mapped database (${dbName}). Credentials resolve live at run time via`);
228
+ lines.push(`# 'solidactions dev --env ${environment}' or in deployed workflows — never stored in this file.`);
229
+ lines.push(`# ${devEnvHintLine(environment)}`);
230
+ // Blank line closes the block (see above) — and keeps the hint
231
+ // the LAST line of this variable's explanation, not something
232
+ // buried mid-way through the next variable's.
233
+ lines.push('');
234
+ databaseVars.push({ key, dbName });
235
+ continue;
236
+ }
160
237
  if (value === null || value === undefined) {
161
238
  // Skip variables with no value
162
239
  lines.push(`# ${key}= (no value configured)`);
@@ -196,6 +273,22 @@ async function envPull(projectName, options = {}) {
196
273
  if (secretCount > 0) {
197
274
  console.log(chalk_1.default.yellow(` (includes ${secretCount} secret value${secretCount > 1 ? 's' : ''})`));
198
275
  }
276
+ // A declared-but-missing database is a different problem from a healthy
277
+ // mapped one, and gets its own note naming what to fix.
278
+ for (const { key, wanted } of unresolvedDatabaseVars) {
279
+ console.log(chalk_1.default.yellow(`\nNOTE: ${key} is a mapped database that was NOT FOUND — check the database name in `
280
+ + `solidactions.yaml: no database named '${wanted}' exists in this workspace.`));
281
+ console.log(chalk_1.default.yellow(` \`solidactions database list\` shows what does; \`solidactions database create ${wanted}\` creates it.`));
282
+ }
283
+ // Say out loud why each mapped database has no value here. The same
284
+ // explanation is written into the .env at the variable's own position;
285
+ // an agent reads one surface or the other, so both must carry it.
286
+ for (const { key, dbName } of databaseVars) {
287
+ console.log(chalk_1.default.cyan(`\nNOTE: ${key} is a mapped database (${dbName}) — credentials are resolved live at run time `
288
+ + `('solidactions dev --env ${environment}' locally, automatic in deployed workflows) `
289
+ + 'and are never written to files.'));
290
+ console.log(chalk_1.default.cyan(` ${devEnvHintLine(environment)}`));
291
+ }
199
292
  // Print any OAuth warnings
200
293
  for (const variable of variables) {
201
294
  if (variable.oauth_warning) {
package/dist/index.js CHANGED
@@ -96,6 +96,7 @@ const database_1 = require("./commands/database");
96
96
  const database_push_1 = require("./commands/database-push");
97
97
  const config_1 = require("./utils/config");
98
98
  const mutating_commands_1 = require("./utils/mutating-commands");
99
+ const agent_freshness_1 = require("./utils/agent-freshness");
99
100
  // eslint-disable-next-line @typescript-eslint/no-var-requires
100
101
  const pkg = require('../package.json');
101
102
  exports.program = new commander_1.Command();
@@ -229,6 +230,24 @@ const database = exports.program
229
230
  .command('database')
230
231
  .description('Manage workspace databases')
231
232
  .addHelpText('after', `
233
+ To USE a database from your code, map it to a project variable and run — don't
234
+ copy the data around. Declare the mapping in solidactions.yaml:
235
+ env:
236
+ - APP_DB:
237
+ database: "<database name>"
238
+ then \`solidactions project deploy <project> <path>\` to register it (\`solidactions env
239
+ list <project>\` shows it), and run locally with:
240
+ solidactions dev <your-workflow-file> --env <env>
241
+ 'dev --env' resolves your platform variables AND every mapped database's
242
+ credentials live from SolidActions — short-lived, held in memory, never written
243
+ to a file — so Drizzle, @libsql/client and drizzle-kit work locally exactly as
244
+ they do in a deployed workflow, which gets the same credentials automatically.
245
+ In your workflow the variable arrives as {name, url, token, readOnly} — pass it
246
+ straight to createDatabaseClient(), or to @libsql/client / Drizzle.
247
+
248
+ 'database import' is for BULK DATA LOADING only (pushing a .sql file into a
249
+ database). It is not how code reads or writes a database at run time.
250
+
232
251
  Connect to a Workspace Database directly (any HTTP client or libSQL-compatible
233
252
  driver): https://www.solidactions.com/docs/workspace-databases/`);
234
253
  database
@@ -808,6 +827,7 @@ ai
808
827
  .description('Install SolidActions AI skills and SDK reference for AI-assisted development')
809
828
  .option('--claude', 'Use CLAUDE.md (for Claude Code)')
810
829
  .option('--agents', 'Use AGENTS.md (for Codex, Cursor, Gemini, Windsurf, etc.)')
830
+ .option('--update', 'Refresh the installed helper target and its version-stamped skills')
811
831
  .action((options) => { (0, ai_init_1.aiInit)(options); });
812
832
  ai
813
833
  .command('examples')
@@ -961,6 +981,7 @@ doc
961
981
  // bin). The #1004 command-manifest generator requires this module to walk the
962
982
  // assembled command tree; that must not consume the caller's argv or exit.
963
983
  if (require.main === module) {
984
+ (0, agent_freshness_1.emitAgentFreshnessNudges)({ currentVersion: pkg.version });
964
985
  exports.program.parseAsync().catch((err) => {
965
986
  console.error(chalk_1.default.red(err.message ?? String(err)));
966
987
  process.exit(1);
@@ -0,0 +1,240 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.UPDATE_CLAIM_SUFFIX = exports.UPDATE_CACHE_FILE = exports.UPDATE_CLAIM_TTL_MS = exports.UPDATE_CHECK_INTERVAL_MS = exports.NUDGE_SUPPRESSION_ENV = void 0;
7
+ exports.isNewerVersion = isNewerVersion;
8
+ exports.isCoworkSandbox = isCoworkSandbox;
9
+ exports.collectAgentFreshness = collectAgentFreshness;
10
+ exports.claimUpdateCheck = claimUpdateCheck;
11
+ exports.launchDetachedUpdateCheck = launchDetachedUpdateCheck;
12
+ exports.emitAgentFreshnessNudges = emitAgentFreshnessNudges;
13
+ const fs_1 = __importDefault(require("fs"));
14
+ const os_1 = __importDefault(require("os"));
15
+ const path_1 = __importDefault(require("path"));
16
+ const child_process_1 = require("child_process");
17
+ const skills_1 = require("./skills");
18
+ // One switch suppresses the complete nudge system, including the background
19
+ // update refresh. This is intentionally broader than muting the four lines:
20
+ // automation that opts out should get neither output nor surprise egress.
21
+ exports.NUDGE_SUPPRESSION_ENV = 'SOLIDACTIONS_NO_AGENT_NUDGES';
22
+ exports.UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
23
+ exports.UPDATE_CLAIM_TTL_MS = 10 * 60 * 1000;
24
+ exports.UPDATE_CACHE_FILE = 'agent-update-check.json';
25
+ exports.UPDATE_CLAIM_SUFFIX = '.claim';
26
+ function safeOneLine(value) {
27
+ return value.replace(/[\u0000-\u001f\u007f]/g, '?');
28
+ }
29
+ function parseVersion(version) {
30
+ const identifier = '[0-9A-Za-z-]+';
31
+ const match = version.match(new RegExp(`^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)`
32
+ + `(?:-(${identifier}(?:\\.${identifier})*))?`
33
+ + `(?:\\+(${identifier}(?:\\.${identifier})*))?$`));
34
+ if (!match)
35
+ return null;
36
+ const prerelease = match[4]?.split('.') ?? [];
37
+ if (prerelease.some((part) => /^\d+$/.test(part) && part.length > 1 && part.startsWith('0'))) {
38
+ return null;
39
+ }
40
+ return {
41
+ core: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])],
42
+ prerelease,
43
+ };
44
+ }
45
+ /** True only when `candidate` is a valid semver newer than `current`. */
46
+ function isNewerVersion(candidate, current) {
47
+ const left = parseVersion(candidate);
48
+ const right = parseVersion(current);
49
+ if (!left || !right)
50
+ return false;
51
+ for (let i = 0; i < 3; i += 1) {
52
+ if (left.core[i] !== right.core[i])
53
+ return left.core[i] > right.core[i];
54
+ }
55
+ if (left.prerelease.length === 0 || right.prerelease.length === 0) {
56
+ return left.prerelease.length === 0 && right.prerelease.length > 0;
57
+ }
58
+ const length = Math.max(left.prerelease.length, right.prerelease.length);
59
+ for (let i = 0; i < length; i += 1) {
60
+ const a = left.prerelease[i];
61
+ const b = right.prerelease[i];
62
+ if (a === undefined || b === undefined)
63
+ return a !== undefined;
64
+ if (a === b)
65
+ continue;
66
+ const aNumeric = /^\d+$/.test(a);
67
+ const bNumeric = /^\d+$/.test(b);
68
+ if (aNumeric && bNumeric)
69
+ return BigInt(a) > BigInt(b);
70
+ if (aNumeric !== bNumeric)
71
+ return !aNumeric;
72
+ return a > b;
73
+ }
74
+ return false;
75
+ }
76
+ function readUpdateCache(cacheFile) {
77
+ try {
78
+ const parsed = JSON.parse(fs_1.default.readFileSync(cacheFile, 'utf8'));
79
+ if (typeof parsed.checkedAt !== 'string')
80
+ return null;
81
+ if (parsed.latestVersion !== undefined && typeof parsed.latestVersion !== 'string')
82
+ return null;
83
+ return { checkedAt: parsed.checkedAt, latestVersion: parsed.latestVersion };
84
+ }
85
+ catch {
86
+ return null;
87
+ }
88
+ }
89
+ function findProjectRoot(startDir) {
90
+ let dir = path_1.default.resolve(startDir);
91
+ while (true) {
92
+ if (fs_1.default.existsSync(path_1.default.join(dir, 'solidactions.yaml')))
93
+ return dir;
94
+ const parent = path_1.default.dirname(dir);
95
+ if (parent === dir)
96
+ return null;
97
+ dir = parent;
98
+ }
99
+ }
100
+ function isCoworkSandbox(env) {
101
+ // Best-effort heuristic: Cowork does not publish a stable detection
102
+ // contract. False positives can be suppressed with the one nudge opt-out.
103
+ if (env.CLAUDE_CODE_IS_COWORK === '1')
104
+ return true;
105
+ return env.CLAUDE_CODE_ENTRYPOINT === 'local-agent' && env.SANDBOX_RUNTIME === '1';
106
+ }
107
+ function collectAgentFreshness(options) {
108
+ const cwd = path_1.default.resolve(options.cwd ?? process.cwd());
109
+ const env = options.env ?? process.env;
110
+ const homeDir = options.homeDir ?? os_1.default.homedir();
111
+ const now = options.now ?? new Date();
112
+ const updateCacheFile = path_1.default.join(homeDir, '.solidactions', exports.UPDATE_CACHE_FILE);
113
+ const suppressed = env[exports.NUDGE_SUPPRESSION_ENV] === '1';
114
+ if (suppressed) {
115
+ return {
116
+ lines: [],
117
+ updateCacheFile,
118
+ updateCache: null,
119
+ shouldRefreshUpdateCache: false,
120
+ };
121
+ }
122
+ const lines = [];
123
+ const updateCache = readUpdateCache(updateCacheFile);
124
+ if (updateCache?.latestVersion && isNewerVersion(updateCache.latestVersion, options.currentVersion)) {
125
+ lines.push(`AGENT NOTE: CLI ${safeOneLine(options.currentVersion)} outdated (${safeOneLine(updateCache.latestVersion)} available); newer versions add verbs not visible in this --help. Run: npm i -g @solidactions/cli`);
126
+ }
127
+ const checkedAt = updateCache ? Date.parse(updateCache.checkedAt) : Number.NaN;
128
+ const shouldRefreshUpdateCache = !Number.isFinite(checkedAt)
129
+ || now.getTime() - checkedAt >= exports.UPDATE_CHECK_INTERVAL_MS
130
+ || checkedAt > now.getTime();
131
+ const projectRoot = findProjectRoot(cwd);
132
+ const installedDirs = projectRoot ? (0, skills_1.findInstalledSkillDirs)(projectRoot) : [];
133
+ if (projectRoot && installedDirs.length === 0) {
134
+ lines.push('AGENT NOTE: Install SolidActions skills for this project. Run: solidactions ai init');
135
+ }
136
+ else if (projectRoot) {
137
+ const staleDir = installedDirs.find((dir) => !(0, skills_1.isSkillDirCurrent)(dir));
138
+ if (staleDir) {
139
+ lines.push(`AGENT NOTE: Refresh stale SolidActions skills at ${safeOneLine(staleDir)}. Run: solidactions ai init --update`);
140
+ }
141
+ }
142
+ if (projectRoot && installedDirs.length > 0 && isCoworkSandbox(env)) {
143
+ const skillsDir = installedDirs[0];
144
+ const safePath = safeOneLine(skillsDir);
145
+ lines.push(`AGENT NOTE: skills at ${safePath} are not auto-loaded in this environment — read ${safePath}/solidactions-*.md (or ${safePath}/*/SKILL.md) before proceeding`);
146
+ }
147
+ return { lines, updateCacheFile, updateCache, shouldRefreshUpdateCache };
148
+ }
149
+ function writeUpdateCheckStarted(cacheFile, cache, now) {
150
+ const dir = path_1.default.dirname(cacheFile);
151
+ fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
152
+ const next = { checkedAt: now.toISOString() };
153
+ if (cache?.latestVersion)
154
+ next.latestVersion = cache.latestVersion;
155
+ const tempFile = `${cacheFile}.${process.pid}.tmp`;
156
+ fs_1.default.writeFileSync(tempFile, `${JSON.stringify(next)}\n`, { mode: 0o600 });
157
+ fs_1.default.renameSync(tempFile, cacheFile);
158
+ }
159
+ /** Atomically own a refresh, or retake a claim abandoned beyond its TTL. */
160
+ function claimUpdateCheck(claimFile, now) {
161
+ fs_1.default.mkdirSync(path_1.default.dirname(claimFile), { recursive: true, mode: 0o700 });
162
+ for (let attempt = 0; attempt < 2; attempt += 1) {
163
+ try {
164
+ // flag: wx maps to O_CREAT | O_EXCL: exactly one concurrent caller wins.
165
+ fs_1.default.writeFileSync(claimFile, `${now.toISOString()}\n`, { flag: 'wx', mode: 0o600 });
166
+ return true;
167
+ }
168
+ catch (error) {
169
+ if (error?.code !== 'EEXIST')
170
+ throw error;
171
+ if (attempt > 0)
172
+ return false;
173
+ let stale = false;
174
+ try {
175
+ stale = now.getTime() - fs_1.default.statSync(claimFile).mtimeMs > exports.UPDATE_CLAIM_TTL_MS;
176
+ }
177
+ catch (statError) {
178
+ if (statError?.code === 'ENOENT')
179
+ continue;
180
+ throw statError;
181
+ }
182
+ if (!stale)
183
+ return false;
184
+ try {
185
+ fs_1.default.unlinkSync(claimFile);
186
+ }
187
+ catch (unlinkError) {
188
+ if (unlinkError?.code !== 'ENOENT')
189
+ throw unlinkError;
190
+ }
191
+ }
192
+ }
193
+ return false;
194
+ }
195
+ function launchDetachedUpdateCheck(cacheFile, claimFile) {
196
+ const worker = path_1.default.join(__dirname, 'agent-update-worker.js');
197
+ const child = (0, child_process_1.spawn)(process.execPath, [worker, cacheFile, claimFile], {
198
+ detached: true,
199
+ stdio: 'ignore',
200
+ windowsHide: true,
201
+ });
202
+ child.on('error', () => {
203
+ try {
204
+ fs_1.default.unlinkSync(claimFile);
205
+ }
206
+ catch { /* best effort */ }
207
+ });
208
+ child.unref();
209
+ }
210
+ /** Emit all applicable lines to stderr. Every failure is deliberately ignored. */
211
+ function emitAgentFreshnessNudges(options) {
212
+ try {
213
+ const result = collectAgentFreshness(options);
214
+ for (const line of result.lines)
215
+ process.stderr.write(`${line}\n`);
216
+ if (result.shouldRefreshUpdateCache) {
217
+ const now = options.now ?? new Date();
218
+ const claimFile = `${result.updateCacheFile}${exports.UPDATE_CLAIM_SUFFIX}`;
219
+ // O_EXCL elects one owner. A live claim skips this invocation;
220
+ // an abandoned claim becomes eligible for takeover after its TTL.
221
+ if (claimUpdateCheck(claimFile, now)) {
222
+ try {
223
+ writeUpdateCheckStarted(result.updateCacheFile, result.updateCache, now);
224
+ (options.launchUpdateCheck ?? launchDetachedUpdateCheck)(result.updateCacheFile, claimFile);
225
+ }
226
+ catch (error) {
227
+ try {
228
+ fs_1.default.unlinkSync(claimFile);
229
+ }
230
+ catch { /* best effort */ }
231
+ throw error;
232
+ }
233
+ }
234
+ }
235
+ }
236
+ catch {
237
+ // Nudges are advisory: read-only commands, JSON output, and scripts must
238
+ // continue even when HOME is unwritable or state is malformed.
239
+ }
240
+ }
@@ -0,0 +1,65 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ const fs_1 = __importDefault(require("fs"));
7
+ const https_1 = __importDefault(require("https"));
8
+ const path_1 = __importDefault(require("path"));
9
+ const cacheFile = process.argv[2];
10
+ const claimFile = process.argv[3];
11
+ const registryUrl = 'https://registry.npmjs.org/@solidactions%2Fcli/latest';
12
+ let finished = false;
13
+ function finish() {
14
+ if (finished)
15
+ return;
16
+ finished = true;
17
+ if (claimFile) {
18
+ try {
19
+ fs_1.default.unlinkSync(claimFile);
20
+ }
21
+ catch { /* best effort */ }
22
+ }
23
+ }
24
+ function writeCache(latestVersion) {
25
+ const dir = path_1.default.dirname(cacheFile);
26
+ fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
27
+ const tempFile = `${cacheFile}.${process.pid}.tmp`;
28
+ fs_1.default.writeFileSync(tempFile, `${JSON.stringify({ checkedAt: new Date().toISOString(), latestVersion })}\n`, { mode: 0o600 });
29
+ fs_1.default.renameSync(tempFile, cacheFile);
30
+ }
31
+ if (cacheFile) {
32
+ const request = https_1.default.get(registryUrl, {
33
+ headers: { accept: 'application/json', 'user-agent': '@solidactions/cli update check' },
34
+ timeout: 5_000,
35
+ }, (response) => {
36
+ if (response.statusCode !== 200) {
37
+ response.resume();
38
+ response.on('end', finish);
39
+ return;
40
+ }
41
+ let body = '';
42
+ response.setEncoding('utf8');
43
+ response.on('data', (chunk) => {
44
+ if (body.length <= 64 * 1024)
45
+ body += chunk;
46
+ });
47
+ response.on('end', () => {
48
+ try {
49
+ const version = JSON.parse(body)?.version;
50
+ if (typeof version === 'string' && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
51
+ writeCache(version);
52
+ }
53
+ }
54
+ catch {
55
+ // Offline, malformed, and unwritable-cache failures are silent.
56
+ }
57
+ finally {
58
+ finish();
59
+ }
60
+ });
61
+ response.on('error', finish);
62
+ });
63
+ request.on('timeout', () => request.destroy());
64
+ request.on('error', finish);
65
+ }
@@ -29,9 +29,11 @@ exports.EXAMPLES_REF = void 0;
29
29
  * SDK, replace this with a derivation the way sdk-version.ts does.
30
30
  *
31
31
  * Currently: the merged solidactions-examples mainline as of CLI v3.8.0
32
- * (includes ex#31 "refresh workspace database guidance"). Repinned at release
33
- * per the standing #1146 contract: on every CLI release, repin EXAMPLES_REF to
34
- * the examples repo's merged mainline SHA and verify the exact ref during the
35
- * release ritual.
32
+ * (includes ex#34 "workspace-database + Drizzle example", which is what makes
33
+ * `ai examples` able to install workspace-database-drizzle — the runnable
34
+ * connect + drizzle-kit-migration example #140 exists to point people at).
35
+ * Repinned at release per the standing #1146 contract: on every CLI release,
36
+ * repin EXAMPLES_REF to the examples repo's merged mainline SHA and verify the
37
+ * exact ref during the release ritual.
36
38
  */
37
- exports.EXAMPLES_REF = '5eaaaab417ef510401618b814a1eedf238752057';
39
+ exports.EXAMPLES_REF = '47e887d348b45ab948c904a29c1354cbbc23cdab';
@@ -3,16 +3,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.SOLIDACTIONS_SKILL_NAMES = void 0;
6
+ exports.SOLIDACTIONS_SKILL_NAMES = exports.SKILLS_VERSION_FILE = exports.BUNDLED_SKILLS_VERSION = void 0;
7
7
  exports.skillTargetDir = skillTargetDir;
8
8
  exports.installSkills = installSkills;
9
9
  exports.fetchAiHelperContent = fetchAiHelperContent;
10
10
  exports.hasSolidActionsSkills = hasSolidActionsSkills;
11
+ exports.findInstalledSkillDirs = findInstalledSkillDirs;
12
+ exports.isSkillDirCurrent = isSkillDirCurrent;
11
13
  const fs_1 = __importDefault(require("fs"));
12
14
  const path_1 = __importDefault(require("path"));
13
15
  const fs_extra_1 = __importDefault(require("fs-extra"));
14
16
  const github_1 = require("./github");
15
17
  const examples_ref_1 = require("./examples-ref");
18
+ exports.BUNDLED_SKILLS_VERSION = examples_ref_1.EXAMPLES_REF;
19
+ exports.SKILLS_VERSION_FILE = '.solidactions-version';
16
20
  exports.SOLIDACTIONS_SKILL_NAMES = [
17
21
  'solidactions-getting-started',
18
22
  'solidactions-workflow-coding',
@@ -53,6 +57,11 @@ async function installSkills(targetDir) {
53
57
  fs_1.default.writeFileSync(filePath, content, 'utf8');
54
58
  written.push(filePath);
55
59
  }
60
+ // Stamp only after every fetch/write succeeds. A partial/offline install
61
+ // must remain visibly stale so the next run can tell the agent to repair it.
62
+ const versionFile = path_1.default.join(targetDir, exports.SKILLS_VERSION_FILE);
63
+ fs_1.default.writeFileSync(versionFile, `${exports.BUNDLED_SKILLS_VERSION}\n`, 'utf8');
64
+ written.push(versionFile);
56
65
  return { written };
57
66
  }
58
67
  /**
@@ -68,15 +77,33 @@ async function fetchAiHelperContent(targetFile) {
68
77
  * these files are how AI assistants self-rescue on env-scope/deploy traps.
69
78
  */
70
79
  function hasSolidActionsSkills(projectDir) {
80
+ return findInstalledSkillDirs(projectDir).length > 0;
81
+ }
82
+ /** Return every helper-specific directory containing SolidActions skills. */
83
+ function findInstalledSkillDirs(projectDir) {
84
+ const installed = [];
71
85
  for (const target of ['CLAUDE.md', 'AGENTS.md']) {
72
86
  const dir = skillTargetDir(target, projectDir);
73
87
  if (!fs_1.default.existsSync(dir)) {
74
88
  continue;
75
89
  }
76
- const entries = fs_1.default.readdirSync(dir);
77
- if (entries.some((f) => f.startsWith('solidactions-') && f.endsWith('.md'))) {
78
- return true;
90
+ try {
91
+ const entries = fs_1.default.readdirSync(dir);
92
+ if (entries.some((f) => f.startsWith('solidactions-') && f.endsWith('.md'))) {
93
+ installed.push(dir);
94
+ }
95
+ }
96
+ catch {
97
+ // Advisory discovery must not make an otherwise valid CLI command fail.
79
98
  }
80
99
  }
81
- return false;
100
+ return installed;
101
+ }
102
+ function isSkillDirCurrent(skillDir) {
103
+ try {
104
+ return fs_1.default.readFileSync(path_1.default.join(skillDir, exports.SKILLS_VERSION_FILE), 'utf8').trim() === exports.BUNDLED_SKILLS_VERSION;
105
+ }
106
+ catch {
107
+ return false;
108
+ }
82
109
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@solidactions/cli",
3
- "version": "3.15.0",
3
+ "version": "3.16.0",
4
4
  "description": "SolidActions CLI - Deploy and manage workflow automation",
5
5
  "main": "dist/index.js",
6
6
  "bin": {