@solidactions/cli 3.15.0 → 3.17.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.
@@ -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,11 +230,30 @@ 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
235
254
  .command('list')
236
255
  .description('List workspace databases')
256
+ .option('--kind <kind>', 'Filter by kind: libsql or duckdb')
237
257
  .option('--json', 'Output as JSON')
238
258
  .action(async (options) => {
239
259
  await (0, database_1.databaseList)(options);
@@ -242,11 +262,21 @@ database
242
262
  .command('create')
243
263
  .description('Create a workspace database')
244
264
  .argument('<name>', 'Database name')
265
+ .option('--kind <kind>', 'Database kind: libsql (default) or duckdb', 'libsql')
245
266
  .option('--from <file.sql>', 'Import a SQL file after creation')
267
+ .option('--no-wait', 'Do not wait for analytical (duckdb) provisioning to finish')
246
268
  .option('--json', 'Output as JSON')
247
269
  .action(async (name, options) => {
248
270
  await (0, database_1.databaseCreate)(name, options);
249
271
  });
272
+ database
273
+ .command('show')
274
+ .description('Show database details')
275
+ .argument('<name>', 'Database name')
276
+ .option('--json', 'Output as JSON')
277
+ .action(async (name, options) => {
278
+ await (0, database_1.databaseShow)(name, options);
279
+ });
250
280
  database
251
281
  .command('delete')
252
282
  .description('Delete a workspace database')
@@ -277,6 +307,7 @@ database
277
307
  .description('Run a read-only SQL query')
278
308
  .argument('<name>', 'Database name')
279
309
  .argument('<sql>', 'SQL query')
310
+ .option('--limit <n>', 'Row cap for analytical queries (max 10000)', (value) => parseInt(value, 10))
280
311
  .option('--json', 'Output as JSON')
281
312
  .action(async (name, sql, options) => {
282
313
  await (0, database_1.databaseQuery)(name, sql, options);
@@ -336,6 +367,53 @@ virtual, and shadow tables are excluded from the count.`)
336
367
  .action(async (name, file, options) => {
337
368
  await (0, database_push_1.databasePush)(name, file, options);
338
369
  });
370
+ database
371
+ .command('ingest')
372
+ .description('Load a batch of rows into an analytical database')
373
+ .argument('<name>', 'Database name')
374
+ .argument('<file>', 'Parquet, CSV, or JSONL file to load')
375
+ .requiredOption('--table <table>', 'Target table name')
376
+ .option('--mode <mode>', 'append (default) or replace', 'append')
377
+ .option('--batch-id <id>', 'Idempotency key (default: derived from the file, table, and mode)')
378
+ .option('--json', 'Output as JSON')
379
+ .action(async (name, file, options) => {
380
+ await (0, database_1.databaseIngest)(name, file, { table: options.table, mode: options.mode, batchId: options.batchId, json: options.json });
381
+ });
382
+ database
383
+ .command('drop-table')
384
+ .description('Delete one table from an analytical database and free its space')
385
+ .argument('<name>', 'Database name')
386
+ .argument('<table>', 'Table name')
387
+ .option('-y, --yes', 'Skip confirmation')
388
+ .option('--json', 'Output as JSON')
389
+ .action(async (name, table, options) => {
390
+ await (0, database_1.databaseDropTable)(name, table, options);
391
+ });
392
+ database
393
+ .command('optimize')
394
+ .description('Consolidate an analytical database\'s stored files now')
395
+ .argument('<name>', 'Database name')
396
+ .option('--wait', 'Wait for optimize to finish and print files before/after')
397
+ .option('--json', 'Output as JSON')
398
+ .action(async (name, options) => {
399
+ await (0, database_1.databaseOptimize)(name, options);
400
+ });
401
+ database
402
+ .command('connect')
403
+ .description('Show how to connect to an analytical database')
404
+ .argument('<name>', 'Database name')
405
+ .option('--json', 'Output as JSON')
406
+ .action(async (name, options) => {
407
+ await (0, database_1.databaseConnect)(name, options);
408
+ });
409
+ database
410
+ .command('wake')
411
+ .description('Wake an idle analytical database and wait for it to become active')
412
+ .argument('<name>', 'Database name')
413
+ .option('--json', 'Output as JSON')
414
+ .action(async (name, options) => {
415
+ await (0, database_1.databaseWake)(name, options);
416
+ });
339
417
  // =============================================================================
340
418
  // project <subcommand>
341
419
  // =============================================================================
@@ -808,6 +886,7 @@ ai
808
886
  .description('Install SolidActions AI skills and SDK reference for AI-assisted development')
809
887
  .option('--claude', 'Use CLAUDE.md (for Claude Code)')
810
888
  .option('--agents', 'Use AGENTS.md (for Codex, Cursor, Gemini, Windsurf, etc.)')
889
+ .option('--update', 'Refresh the installed helper target and its version-stamped skills')
811
890
  .action((options) => { (0, ai_init_1.aiInit)(options); });
812
891
  ai
813
892
  .command('examples')
@@ -961,6 +1040,7 @@ doc
961
1040
  // bin). The #1004 command-manifest generator requires this module to walk the
962
1041
  // assembled command tree; that must not consume the caller's argv or exit.
963
1042
  if (require.main === module) {
1043
+ (0, agent_freshness_1.emitAgentFreshnessNudges)({ currentVersion: pkg.version });
964
1044
  exports.program.parseAsync().catch((err) => {
965
1045
  console.error(chalk_1.default.red(err.message ?? String(err)));
966
1046
  process.exit(1);