@solidactions/cli 3.14.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
 
@@ -169,6 +183,18 @@ CWD-inferred workspace differs from that last-written-to one, the CLI warns:
169
183
  warn: workspace changed to <name> — organization <org> (<workspaceId>) — inferred from <path>; last used was <last-used-name-or-id>. Pin it with -w <workspaceId>.
170
184
  ```
171
185
 
186
+ On a fresh install (or a fresh CI container) there's no `state.json` yet, so a CWD-inferred
187
+ write has nothing to compare against. A **write** in that case still warns — once, on that
188
+ first write — even though nothing has "changed":
189
+
190
+ ```
191
+ warn: about to write to <name> — organization <org> (<workspaceId>) — inferred from <path>; no previously recorded workspace to compare against. Pin it with -w <workspaceId>.
192
+ ```
193
+
194
+ This warns and proceeds; it never confirms or refuses. That first write records `state.json`,
195
+ so this line cannot fire again — from then on there is a baseline, and a later CWD-inferred
196
+ write against a *different* workspace gets the `workspace changed to …` treatment above.
197
+
172
198
  For commands that **write** to the server, it also asks for confirmation before proceeding:
173
199
 
174
200
  ```
@@ -452,7 +478,7 @@ You do **not** need `--overwrite` to keep an edited file whose doc was deleted o
452
478
 
453
479
  | Command | Key Flags | Description |
454
480
  |---------|-----------|-------------|
455
- | `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) |
456
482
  | `ai examples [names...]` | `--all`, `--overwrite` | Install example workflows |
457
483
 
458
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.14.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) {
@@ -307,17 +307,12 @@ async function completeLogin(config, workspaces, options, scope = null, prefligh
307
307
  config.workspace = match.slug ?? match.name;
308
308
  config.workspaceId = match.id;
309
309
  }
310
- else if (workspaces.length === 1) {
311
- const selected = workspaces[0];
312
- console.log(chalk_1.default.gray(`Auto-selected workspace: ${(0, workspace_lookup_1.formatWorkspaceWithOrg)(selected)}`));
313
- config.workspace = selected.slug ?? selected.name;
314
- config.workspaceId = selected.id;
315
- }
316
- else if (workspaces.length === 0) {
317
- console.log(chalk_1.default.yellow('No workspaces found. Create one at your SolidActions dashboard, then '
318
- + 'run `solidactions workspace set <name>`.'));
319
- }
320
- else if (process.stdin.isTTY) {
310
+ else if (workspaces.length <= 1 || process.stdin.isTTY) {
311
+ // 0 and 1 workspace need no interactive prompt, but their status copy
312
+ // ("No workspaces found."/"Auto-selected workspace:") already lives in
313
+ // selectWorkspaceInteractively (cli#137, on stderr) — route them
314
+ // through it too so those strings have exactly one call site instead
315
+ // of a stdout duplicate here (app#1482).
321
316
  const selectWorkspace = dependencies.selectWorkspace ?? workspace_lookup_1.selectWorkspaceInteractively;
322
317
  const selected = await selectWorkspace(workspaces);
323
318
  if (selected) {
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();
@@ -140,7 +141,7 @@ exports.program.hook('preAction', (thisCommand, actionCommand) => {
140
141
  for (let cmd = actionCommand; cmd && cmd !== exports.program; cmd = cmd.parent) {
141
142
  commandPath.unshift(cmd.name());
142
143
  }
143
- (0, mutating_commands_1.setActiveCommandPath)(commandPath);
144
+ (0, mutating_commands_1.setActiveCommandPath)(commandPath, actionCommand.opts());
144
145
  const opts = thisCommand.opts();
145
146
  const wsOverride = opts.workspaceOverride;
146
147
  if (wsOverride) {
@@ -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
+ }
package/dist/utils/api.js CHANGED
@@ -451,6 +451,16 @@ async function applyWorkspaceGuard(config, sources, options, io = {}) {
451
451
  + `— inferred from ${inferredFrom}; last used was ${lastLabel}. `
452
452
  + `Pin it with -w ${config.workspaceId}.`);
453
453
  }
454
+ if (action === 'warn-no-baseline') {
455
+ // Fresh install / fresh CI container: no state.json exists yet, so there is nothing
456
+ // to compare against. This warns once, on write #1, and deliberately does NOT confirm
457
+ // or refuse — ADR 0002 rejected "always confirm CWD-inferred writes", and refusing here
458
+ // would break every fresh CI runner that infers its workspace from CWD (app#1481).
459
+ const inferredFrom = sources.workspaceId;
460
+ warn(chalk_1.default.yellow('warn:') + ` about to write to ${describeWorkspace(config, sources)} `
461
+ + `— inferred from ${inferredFrom}; no previously recorded workspace to compare against. `
462
+ + `Pin it with -w ${config.workspaceId}.`);
463
+ }
454
464
  if (action === 'confirm') {
455
465
  // Consent to a workspace is exactly two things: stating it explicitly (-w /
456
466
  // SOLIDACTIONS_WORKSPACE_ID, both of which make this branch unreachable), or
@@ -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';
@@ -16,21 +16,30 @@
16
16
  * `action` argument instead of the outer HTTP verb ('list'/'read' = read,
17
17
  * 'create'/'edit'/'delete'/'take_snapshot'/'sandbox_exec' = write).
18
18
  *
19
- * Classification is per command PATH only — it does not see flags. A
20
- * command that can write under some flag combination but not others (e.g.
21
- * `database pull --writable`) must still be classified MUTATING wholesale;
22
- * there is no flag-aware variant of this lookup. Over-inclusion is the
23
- * intended bias: the workspace-mismatch guard this file feeds only prompts
19
+ * Classification is per command PATH only, by default — it does not see
20
+ * flags. Over-inclusion is the intended bias for anything not explicitly
21
+ * refined below: the workspace-mismatch guard this file feeds only prompts
24
22
  * when the resolved workspace ALSO changed and was CWD-inferred, so
25
23
  * classifying a mostly-read command as MUTATING costs at most one extra
26
24
  * confirmation, whereas the reverse can silently write to the wrong
27
25
  * workspace.
26
+ *
27
+ * FLAG_SENSITIVE_COMMANDS below is a narrow, deliberate refinement layer on
28
+ * top of that path-only answer: a handful of leaves genuinely change from
29
+ * read to write depending on a flag (e.g. `database pull --writable`, which
30
+ * opens a live write REPL instead of just writing a local file). Those
31
+ * leaves stay listed in MUTATING_COMMANDS — the conservative, path-only
32
+ * fail-safe — and isMutatingCommand() only consults the flag predicate when
33
+ * it is given actual options to check; called with no options, or for a
34
+ * path that has no entry in the table, it falls straight through to the
35
+ * path-only answer above.
28
36
  */
29
37
  Object.defineProperty(exports, "__esModule", { value: true });
30
- exports.READONLY_COMMANDS = exports.MUTATING_COMMANDS = void 0;
38
+ exports.FLAG_SENSITIVE_COMMANDS = exports.READONLY_COMMANDS = exports.MUTATING_COMMANDS = void 0;
31
39
  exports.isMutatingCommand = isMutatingCommand;
32
40
  exports.setActiveCommandPath = setActiveCommandPath;
33
41
  exports.getActiveCommandPath = getActiveCommandPath;
42
+ exports.getActiveCommandOptions = getActiveCommandOptions;
34
43
  exports.activeCommandIsMutating = activeCommandIsMutating;
35
44
  /** Space-joined command paths that mutate SERVER state, e.g. 'project deploy'. */
36
45
  exports.MUTATING_COMMANDS = new Set([
@@ -45,10 +54,10 @@ exports.MUTATING_COMMANDS = new Set([
45
54
  // (databaseWritablePullWithConfig, src/commands/database.ts:1320) mints
46
55
  // a WRITE-mode credential and opens a live interactive SQL REPL that
47
56
  // executes real statements (client.execute/executeMultiple, ~lines
48
- // 1540-1560) against the server-backed replica. Classification can't see
49
- // flags, so the whole leaf must be MUTATING to keep the workspace guard
50
- // from silently letting --writable writes through against the wrong
51
- // CWD-inferred workspace.
57
+ // 1540-1560) against the server-backed replica. This is the path-only
58
+ // fail-safe answer (kept for callers that don't pass options, and for
59
+ // completeness/disjointness); FLAG_SENSITIVE_COMMANDS below refines it
60
+ // to the exact `--writable` boundary when options are available.
52
61
  'database pull',
53
62
  'project create',
54
63
  'project deploy',
@@ -136,16 +145,40 @@ exports.READONLY_COMMANDS = new Set([
136
145
  'skill run',
137
146
  'doc pull',
138
147
  ]);
148
+ /**
149
+ * Command paths whose read/write nature depends on a flag rather than being
150
+ * fixed by path alone. Each predicate takes the leaf command's own parsed
151
+ * options and returns true when that flag combination makes the command a
152
+ * SERVER WRITE. This table is a deliberate hole in the path-only fail-safe
153
+ * above — keep it tiny, and keep the corresponding leaf in MUTATING_COMMANDS
154
+ * so any caller that can't supply options still gets the conservative
155
+ * answer.
156
+ */
157
+ exports.FLAG_SENSITIVE_COMMANDS = new Map([
158
+ ['database pull', (options) => options.writable === true],
159
+ ]);
139
160
  /**
140
161
  * True when the given commander path is a server-mutating command.
141
162
  *
142
- * A path not present in either MUTATING_COMMANDS or READONLY_COMMANDS
143
- * returns true (fail safe): an unclassified command is treated as a write,
144
- * so a newly-added command can never silently skip the workspace-mismatch
145
- * guard.
163
+ * When `options` is supplied and the path has an entry in
164
+ * FLAG_SENSITIVE_COMMANDS, that entry's predicate decides the answer
165
+ * exactly — this is the only way a `database pull` without `--writable` is
166
+ * classified as read-only. Without options (the caller didn't observe any
167
+ * flags, or the path isn't flag-sensitive), classification falls through to
168
+ * the path-only tables: a path not present in either MUTATING_COMMANDS or
169
+ * READONLY_COMMANDS returns true (fail safe) — an unclassified command is
170
+ * treated as a write, so a newly-added command can never silently skip the
171
+ * workspace-mismatch guard, and an unobserved-flags lookup never guesses
172
+ * read from absence.
146
173
  */
147
- function isMutatingCommand(path) {
174
+ function isMutatingCommand(path, options) {
148
175
  const key = path.join(' ');
176
+ if (options !== undefined) {
177
+ const predicate = exports.FLAG_SENSITIVE_COMMANDS.get(key);
178
+ if (predicate) {
179
+ return predicate(options);
180
+ }
181
+ }
149
182
  if (exports.MUTATING_COMMANDS.has(key)) {
150
183
  return true;
151
184
  }
@@ -155,22 +188,28 @@ function isMutatingCommand(path) {
155
188
  return true;
156
189
  }
157
190
  let activeCommandPath = undefined;
191
+ let activeCommandOptions = undefined;
158
192
  /**
159
- * Set the command path from the commander `preAction` hook.
160
- * Module-level state — set once at CLI startup before the command runs.
161
- * Pass `undefined` to clear (used in tests).
193
+ * Set the command path (and its own parsed options) from the commander
194
+ * `preAction` hook. Module-level state — set once at CLI startup before the
195
+ * command runs. Pass `undefined` for both to clear (used in tests).
162
196
  */
163
- function setActiveCommandPath(path) {
197
+ function setActiveCommandPath(path, options) {
164
198
  activeCommandPath = path;
199
+ activeCommandOptions = path === undefined ? undefined : options;
165
200
  }
166
201
  /** The path recorded by setActiveCommandPath, or undefined. */
167
202
  function getActiveCommandPath() {
168
203
  return activeCommandPath;
169
204
  }
205
+ /** The options recorded by setActiveCommandPath, or undefined. */
206
+ function getActiveCommandOptions() {
207
+ return activeCommandOptions;
208
+ }
170
209
  /** True when the recorded active command is mutating. False when nothing was recorded. */
171
210
  function activeCommandIsMutating() {
172
211
  if (activeCommandPath === undefined) {
173
212
  return false;
174
213
  }
175
- return isMutatingCommand(activeCommandPath);
214
+ return isMutatingCommand(activeCommandPath, activeCommandOptions);
176
215
  }
@@ -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
  }
@@ -84,14 +84,15 @@ function writeLastUsedWorkspace(entry, homeDir = os_1.default.homedir()) {
84
84
  }
85
85
  /**
86
86
  * Decision table:
87
- * | condition | result |
88
- * |----------------------------------------------------------------|-----------|
89
- * | resolvedWorkspaceId falsy | 'none' |
90
- * | cwdInferred is false | 'none' |
91
- * | lastUsedWorkspaceId falsy (first run, do not nag) | 'none' |
92
- * | resolved === lastUsed | 'none' |
93
- * | resolved !== lastUsed, mutating false | 'warn' |
94
- * | resolved !== lastUsed, mutating true | 'confirm' |
87
+ * | condition | result |
88
+ * |------------------------------------------------------------------|--------------------|
89
+ * | resolvedWorkspaceId falsy | 'none' |
90
+ * | cwdInferred is false | 'none' |
91
+ * | lastUsedWorkspaceId falsy, mutating true (fresh install, first write) | 'warn-no-baseline' |
92
+ * | lastUsedWorkspaceId falsy, mutating false (reads stay frictionless) | 'none' |
93
+ * | resolved === lastUsed | 'none' |
94
+ * | resolved !== lastUsed, mutating false | 'warn' |
95
+ * | resolved !== lastUsed, mutating true | 'confirm' |
95
96
  */
96
97
  function decideWorkspaceGuard(input) {
97
98
  if (!input.resolvedWorkspaceId) {
@@ -101,7 +102,11 @@ function decideWorkspaceGuard(input) {
101
102
  return 'none';
102
103
  }
103
104
  if (!input.lastUsedWorkspaceId) {
104
- return 'none';
105
+ // Deliberate: readLastUsedWorkspace() returns null for an absent state.json AND for
106
+ // an unreadable/malformed one. Both mean "no baseline to compare against" — an
107
+ // unreadable baseline is an unknown baseline, not a known-safe one — so both take
108
+ // the same conservative branch: warn on a write rather than silently confirming.
109
+ return input.mutating ? 'warn-no-baseline' : 'none';
105
110
  }
106
111
  if (input.resolvedWorkspaceId === input.lastUsedWorkspaceId) {
107
112
  return 'none';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@solidactions/cli",
3
- "version": "3.14.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": {