@solidactions/cli 3.38.0 → 3.40.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/dist/index.js CHANGED
@@ -102,6 +102,7 @@ const database_1 = require("./commands/database");
102
102
  const database_push_1 = require("./commands/database-push");
103
103
  const database_export_1 = require("./commands/database-export");
104
104
  const config_1 = require("./utils/config");
105
+ const database_pull_guidance_1 = require("./utils/database-pull-guidance");
105
106
  const host_display_1 = require("./utils/host-display");
106
107
  const mutating_commands_1 = require("./utils/mutating-commands");
107
108
  const agent_freshness_1 = require("./utils/agent-freshness");
@@ -287,8 +288,18 @@ list <project>\` shows it), and run locally with:
287
288
  credentials live from SolidActions — short-lived, held in memory, never written
288
289
  to a file — so Drizzle, @libsql/client and drizzle-kit work locally exactly as
289
290
  they do in a deployed workflow, which gets the same credentials automatically.
290
- In your workflow the variable arrives as {name, url, token, readOnly} — pass it
291
- straight to createDatabaseClient(), or to @libsql/client / Drizzle.
291
+ For a standard (libSQL) database, the variable arrives as {name, url, token,
292
+ readOnly} — pass it straight to createDatabaseClient(), or to @libsql/client /
293
+ Drizzle.
294
+
295
+ A DuckDB database file (--kind duckdb_file) is a different kind: bind it with
296
+ database: "<database name>" in solidactions.yaml the same way (the run env
297
+ carries its database id string), then open it in a workflow with openAnalytics
298
+ from @solidactions/sdk 0.11.0 or newer (add @duckdb/node-api as a normal
299
+ dependency: npm install @duckdb/node-api, not --save-dev). Read it with
300
+ \`solidactions database query\` and \`solidactions database schema\`, download
301
+ it with \`solidactions database pull\`, and list and restore versions with
302
+ \`solidactions database versions\` and \`solidactions database rollback\`.
292
303
 
293
304
  'database import' is for BULK DATA LOADING only (pushing a .sql file into a
294
305
  database). It is not how code reads or writes a database at run time.
@@ -299,6 +310,7 @@ database
299
310
  .command('list')
300
311
  .description('List workspace databases')
301
312
  .option('--kind <kind>', 'Filter by kind: libsql, duckdb or duckdb_file')
313
+ .option('--include-deleted', 'Include deleted databases (they can be restored with database undelete until they are purged)')
302
314
  .option('--json', 'Output as JSON')
303
315
  .action(async (options) => {
304
316
  await (0, database_1.databaseList)(options);
@@ -324,7 +336,7 @@ database
324
336
  });
325
337
  database
326
338
  .command('delete')
327
- .description('Delete a workspace database')
339
+ .description('Delete a workspace database (soft-delete: database list --include-deleted still shows it until purged; restore with database undelete)')
328
340
  .argument('<name>', 'Database name')
329
341
  .option('-y, --yes', 'Skip confirmation')
330
342
  .option('--json', 'Output as JSON')
@@ -333,7 +345,7 @@ database
333
345
  });
334
346
  database
335
347
  .command('undelete')
336
- .description('Restore a deleted workspace database')
348
+ .description('Restore a deleted workspace database (find it with database list --include-deleted)')
337
349
  .argument('<name>', 'Database name')
338
350
  .option('--json', 'Output as JSON')
339
351
  .action(async (name, options) => {
@@ -352,7 +364,7 @@ database
352
364
  .description('Run a read-only SQL query')
353
365
  .argument('<name>', 'Database name')
354
366
  .argument('<sql>', 'SQL query')
355
- .option('--limit <n>', 'Row cap for analytical queries (max 10000)', (value) => parseInt(value, 10))
367
+ .option('--limit <n>', 'Maximum rows to return (analytical databases: up to 10000; DuckDB database files: the server caps it, 1000 by default)', (value) => parseInt(value, 10))
356
368
  .option('--json', 'Output as JSON')
357
369
  .action(async (name, sql, options) => {
358
370
  await (0, database_1.databaseQuery)(name, sql, options);
@@ -384,7 +396,8 @@ database
384
396
  .option('-y, --yes', 'Overwrite without confirmation')
385
397
  .option('--writable', 'Open a foreground writable session')
386
398
  .option('--version <n>', 'DuckDB databases: pull this published version instead of the latest', (value) => (0, database_1.parseStrictPositiveInteger)(value))
387
- .addHelpText('after', `
399
+ .option('--no-cache', 'Do not read or write the local replica cache for this pull')
400
+ .addHelpText('after', `${database_pull_guidance_1.DATABASE_PULL_HELP}
388
401
  A DuckDB database (--kind duckdb_file) is saved to .solidactions/databases/<name>.duckdb
389
402
  unless you give a path. Pulling it needs Node 22.15 or newer. List its versions with
390
403
  \`solidactions database versions <name>\`.`)
@@ -0,0 +1,27 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.analyticalVerbKindMismatch = analyticalVerbKindMismatch;
4
+ const database_data_plane_1 = require("./database-data-plane");
5
+ /**
6
+ * Frozen contract 3 (wave cli-duckdb, Task 4): the kind-mismatch refusal for
7
+ * the analytical-only verbs (`connect`, `wake`, `optimize`, `drop-table`,
8
+ * `ingest`, `export`) when the named database is not an analytical (duckdb)
9
+ * database.
10
+ *
11
+ * A DuckDB database file gets the sentence naming the kind; a standard
12
+ * (libsql) database keeps the exact sentence each call site threw before
13
+ * (the `ingest` wording for `verb === 'ingest'`, no normalizing). Returns
14
+ * null for an analytical (duckdb) database, which every caller lets through.
15
+ */
16
+ function analyticalVerbKindMismatch(name, row, verb) {
17
+ if (row.kind === 'duckdb') {
18
+ return null;
19
+ }
20
+ if (row.kind === 'duckdb_file') {
21
+ return new database_data_plane_1.DatabaseOperationError('kind_mismatch', `"${name}" is a DuckDB database file — \`database ${verb}\` does not apply to it. Read it with \`database query\` and \`database schema\`; download it with \`database pull\`; see its history with \`database versions\` and \`database rollback\`.`);
22
+ }
23
+ if (verb === 'ingest') {
24
+ return new database_data_plane_1.DatabaseOperationError('kind_mismatch', `"${name}" is not an analytical database — \`database ingest\` only loads data into analytical (duckdb) databases.`);
25
+ }
26
+ return new database_data_plane_1.DatabaseOperationError('kind_mismatch', `"${name}" is not an analytical database — \`database ${verb}\` only works on analytical (duckdb) databases.`);
27
+ }
@@ -0,0 +1,20 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.DATABASE_PULL_HELP = exports.WORKFLOW_RUN_PULL_WARNING = exports.WORKFLOW_RUN_ENV_KEYS = void 0;
4
+ exports.isInsideWorkflowRun = isInsideWorkflowRun;
5
+ exports.WORKFLOW_RUN_ENV_KEYS = ['SOLIDACTIONS_RUN_ID', 'STEPS_TRIGGER_ID'];
6
+ function isInsideWorkflowRun(env) {
7
+ return exports.WORKFLOW_RUN_ENV_KEYS.some((key) => typeof env[key] === 'string' && env[key] !== '');
8
+ }
9
+ exports.WORKFLOW_RUN_PULL_WARNING = 'Warning: database pull is running inside a workflow run. A workflow or function can query the database directly (ctx.vars with createDatabaseClient); pulling a copy on every run downloads it again each time. Use pull only for local analysis and keep one copy.';
10
+ exports.DATABASE_PULL_HELP = `
11
+ Pull is for analysing a database on your own machine. Inside a workflow or a function,
12
+ query the database directly instead (ctx.vars with createDatabaseClient); never pull per
13
+ run, per test or per preview. Pull once and reuse that copy.
14
+
15
+ A pull fetches only what changed since your last pull of the same database; the first pull
16
+ downloads everything. A hidden cache for each database lives in
17
+ ~/.solidactions/cache/database-replicas (delete the folder to start over) and takes
18
+ roughly the database's size on disk. Your file is always a plain read-only copy.
19
+ Use --no-cache to leave the cache out of one pull.
20
+ `;
@@ -0,0 +1,432 @@
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.ReplicaCacheError = exports.REPLICA_CACHE_HEARTBEAT_MS = exports.REPLICA_CACHE_STALE_RECLAIM_MS = exports.REPLICA_CACHE_STALE_LOCK_MS = exports.REPLICA_CACHE_SKIP_MS = exports.REPLICA_CACHE_REPLACEMENT_WINDOW_MS = exports.REPLICA_CACHE_REPLACEMENT_LIMIT = void 0;
7
+ exports.defaultReplicaCacheRoot = defaultReplicaCacheRoot;
8
+ exports.replicaCacheKey = replicaCacheKey;
9
+ exports.syncOriginOf = syncOriginOf;
10
+ exports.acquireReplicaCache = acquireReplicaCache;
11
+ /**
12
+ * The hidden per-database replica cache behind `database pull` (cli#262, plan D2-D5).
13
+ * Layout: `<root>/<key>/{lock,lock.reclaim,meta.json,snapshot.tmp,data/}`; everything libSQL
14
+ * creates lives under `data/`, so a wipe removes `data/` whole. A replaced server copy (D3)
15
+ * wipes `data/`; a stale lock (D4) is reclaimed only under `lock.reclaim`. Every cache problem
16
+ * answers `skipped` (D5). Nothing here touches anything outside `<root>/<key>/` (apart from
17
+ * creating `<root>`) or stores a credential (I4).
18
+ */
19
+ const crypto_1 = __importDefault(require("crypto"));
20
+ const fs_1 = __importDefault(require("fs"));
21
+ const os_1 = __importDefault(require("os"));
22
+ const path_1 = __importDefault(require("path"));
23
+ exports.REPLICA_CACHE_REPLACEMENT_LIMIT = 3;
24
+ exports.REPLICA_CACHE_REPLACEMENT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
25
+ exports.REPLICA_CACHE_SKIP_MS = 7 * 24 * 60 * 60 * 1000;
26
+ exports.REPLICA_CACHE_STALE_LOCK_MS = 60 * 60 * 1000;
27
+ exports.REPLICA_CACHE_STALE_RECLAIM_MS = 60 * 1000;
28
+ /** How often a held lock's mtime is refreshed, so another host never judges a live lock stale (I5). */
29
+ exports.REPLICA_CACHE_HEARTBEAT_MS = 5 * 60 * 1000;
30
+ class ReplicaCacheError extends Error {
31
+ }
32
+ exports.ReplicaCacheError = ReplicaCacheError;
33
+ const IDENTITY_FIELDS = ['databaseId', 'createdAt', 'syncOrigin'];
34
+ /** `<homedir>/.solidactions/cache/database-replicas`. */
35
+ function defaultReplicaCacheRoot(homedir = os_1.default.homedir()) {
36
+ return path_1.default.join(homedir, '.solidactions', 'cache', 'database-replicas');
37
+ }
38
+ /** First 32 hex characters of sha256(JSON.stringify([host, workspaceId, name])). */
39
+ function replicaCacheKey(identity) {
40
+ return crypto_1.default.createHash('sha256').update(JSON.stringify([identity.host, identity.workspaceId, identity.name])).digest('hex').slice(0, 32);
41
+ }
42
+ /** Lower-cased `host[:port]` of a `libsql://`, `https://` or `http://` URL; null when it cannot be read. */
43
+ function syncOriginOf(syncUrl) {
44
+ if (typeof syncUrl !== 'string' || syncUrl === '')
45
+ return null;
46
+ let parsed;
47
+ try {
48
+ parsed = new URL(syncUrl);
49
+ }
50
+ catch {
51
+ return null;
52
+ }
53
+ if (!['libsql:', 'https:', 'http:'].includes(parsed.protocol))
54
+ return null;
55
+ const origin = parsed.host.toLowerCase();
56
+ return origin === '' ? null : origin;
57
+ }
58
+ /** Never throws for a cache problem: it answers `skipped` instead. */
59
+ async function acquireReplicaCache(options) {
60
+ const filesystem = options.filesystem ?? fs_1.default.promises;
61
+ const { now, identity } = options;
62
+ const dir = path_1.default.join(options.root, replicaCacheKey(identity));
63
+ const lockPath = path_1.default.join(dir, 'lock');
64
+ const ours = { pid: options.pid ?? process.pid, host: options.hostname ?? os_1.default.hostname(), nonce: crypto_1.default.randomUUID(), at: now() };
65
+ let cache = null;
66
+ try {
67
+ // Any error from here on (a root that cannot be created included) answers `unavailable` below.
68
+ await filesystem.mkdir(options.root, { recursive: true, mode: 0o700 });
69
+ await filesystem.mkdir(dir, { recursive: true, mode: 0o700 });
70
+ if (!(await filesystem.lstat(dir)).isDirectory())
71
+ return { kind: 'skipped', reason: 'unavailable' };
72
+ const locked = await takeLock(filesystem, dir, ours, now, options.processAlive ?? defaultProcessAlive);
73
+ if (!locked)
74
+ return { kind: 'skipped', reason: 'busy' };
75
+ cache = new CacheHandle(filesystem, dir, lockPath, ours.nonce, now);
76
+ cache.startHeartbeat(options.heartbeatMs ?? exports.REPLICA_CACHE_HEARTBEAT_MS);
77
+ await filesystem.rm(cache.snapshotPath, { force: true });
78
+ const stored = await readMeta(filesystem, path_1.default.join(dir, 'meta.json'));
79
+ const meta = stored === null || stored === 'missing' ? defaultMeta() : stored;
80
+ cache.meta = meta;
81
+ // A corrupt meta, or a missing one beside a non-empty data/, leaves a replica of unknown origin (I6).
82
+ if (stored === null || (stored === 'missing' && await isNonEmptyDirectory(filesystem, path_1.default.join(dir, 'data'))))
83
+ await cache.wipe();
84
+ if (meta.skipUntil !== null && meta.skipUntil > now()) {
85
+ await cache.release();
86
+ return { kind: 'skipped', reason: 'rewritten_often' };
87
+ }
88
+ const replaced = IDENTITY_FIELDS.some((field) => meta[field] !== null && identity[field] !== null && meta[field] !== identity[field]);
89
+ for (const field of IDENTITY_FIELDS) {
90
+ const offered = identity[field];
91
+ if (offered !== null)
92
+ meta[field] = offered;
93
+ }
94
+ if (replaced) {
95
+ await cache.wipe();
96
+ const at = now();
97
+ meta.replacements = [...meta.replacements, at].filter((when) => at - when <= exports.REPLICA_CACHE_REPLACEMENT_WINDOW_MS);
98
+ if (meta.replacements.length >= exports.REPLICA_CACHE_REPLACEMENT_LIMIT) {
99
+ meta.skipUntil = at + exports.REPLICA_CACHE_SKIP_MS;
100
+ await cache.writeMeta();
101
+ await cache.release();
102
+ return { kind: 'skipped', reason: 'rewritten_often' };
103
+ }
104
+ }
105
+ await cache.writeMeta();
106
+ const dataDir = path_1.default.join(dir, 'data');
107
+ if ((await lstatIfPresent(filesystem, dataDir)) === null)
108
+ await filesystem.mkdir(dataDir, { mode: 0o700 });
109
+ if (!(await filesystem.lstat(dataDir)).isDirectory()) {
110
+ await cache.release();
111
+ return { kind: 'skipped', reason: 'unavailable' };
112
+ }
113
+ cache.warm = (await lstatIfPresent(filesystem, cache.replicaPath))?.isFile() === true;
114
+ return { kind: 'ready', cache };
115
+ }
116
+ catch {
117
+ if (cache !== null)
118
+ await cache.release();
119
+ return { kind: 'skipped', reason: 'unavailable' };
120
+ }
121
+ }
122
+ class CacheHandle {
123
+ filesystem;
124
+ dir;
125
+ lockPath;
126
+ nonce;
127
+ now;
128
+ replicaPath;
129
+ snapshotPath;
130
+ warm = false;
131
+ meta = defaultMeta();
132
+ released = false;
133
+ heartbeat = null;
134
+ dataDir;
135
+ constructor(filesystem, dir, lockPath, nonce, now) {
136
+ this.filesystem = filesystem;
137
+ this.dir = dir;
138
+ this.lockPath = lockPath;
139
+ this.nonce = nonce;
140
+ this.now = now;
141
+ this.dataDir = path_1.default.join(dir, 'data');
142
+ this.replicaPath = path_1.default.join(this.dataDir, 'replica.db');
143
+ this.snapshotPath = path_1.default.join(dir, 'snapshot.tmp');
144
+ }
145
+ /** Refreshes the lock's mtime every `intervalMs` while it is still ours; the timer never keeps the process alive. */
146
+ startHeartbeat(intervalMs) {
147
+ this.heartbeat = setInterval(() => {
148
+ void this.refreshLock();
149
+ }, intervalMs);
150
+ this.heartbeat.unref();
151
+ }
152
+ async refreshLock() {
153
+ try {
154
+ const stat = await lstatIfPresent(this.filesystem, this.lockPath);
155
+ if (stat === null || !stat.isFile())
156
+ return;
157
+ const record = parseLockRecord(await this.filesystem.readFile(this.lockPath, 'utf8'));
158
+ if (record === null || record.nonce !== this.nonce || this.released)
159
+ return;
160
+ const at = new Date(this.now());
161
+ await this.filesystem.utimes(this.lockPath, at, at);
162
+ }
163
+ catch {
164
+ // Ignored: a missed refresh only makes the lock look older; the next tick tries again.
165
+ }
166
+ }
167
+ async wipe() {
168
+ try {
169
+ const existing = await lstatIfPresent(this.filesystem, this.dataDir);
170
+ if (existing !== null) {
171
+ if (!existing.isDirectory())
172
+ throw new ReplicaCacheError(`The cache's data folder is not a plain folder: ${this.dataDir}`);
173
+ await this.filesystem.rm(this.dataDir, { recursive: true, force: true });
174
+ }
175
+ await this.filesystem.mkdir(this.dataDir, { mode: 0o700 });
176
+ }
177
+ catch (error) {
178
+ if (error instanceof ReplicaCacheError)
179
+ throw error;
180
+ throw new ReplicaCacheError(`Could not reset the cache's data folder: ${error instanceof Error ? error.message : String(error)}`);
181
+ }
182
+ this.warm = false;
183
+ this.meta.lastSyncedAt = null;
184
+ }
185
+ async discardSnapshot() {
186
+ try {
187
+ await this.filesystem.rm(this.snapshotPath, { force: true });
188
+ }
189
+ catch {
190
+ // Never throws: a snapshot that cannot be removed is removed at the next acquire.
191
+ }
192
+ }
193
+ async markSynced() {
194
+ this.meta.lastSyncedAt = this.now();
195
+ await this.writeMeta();
196
+ }
197
+ async release() {
198
+ if (this.released)
199
+ return;
200
+ this.released = true;
201
+ if (this.heartbeat !== null)
202
+ clearInterval(this.heartbeat);
203
+ this.heartbeat = null;
204
+ await this.discardSnapshot();
205
+ try {
206
+ const stat = await lstatIfPresent(this.filesystem, this.lockPath);
207
+ if (stat === null || !stat.isFile())
208
+ return;
209
+ const record = parseLockRecord(await this.filesystem.readFile(this.lockPath, 'utf8'));
210
+ if (record !== null && record.nonce === this.nonce)
211
+ await this.filesystem.unlink(this.lockPath);
212
+ }
213
+ catch {
214
+ // Never throws: a lock left behind is judged stale and reclaimed by the next pull.
215
+ }
216
+ }
217
+ /** Writes `meta.json` atomically: `meta.json.<nonce>.tmp`, then `rename`. Only the documented keys. */
218
+ async writeMeta() {
219
+ const { databaseId, createdAt, syncOrigin, lastSyncedAt, replacements, skipUntil } = this.meta;
220
+ const body = { version: 1, databaseId, createdAt, syncOrigin, lastSyncedAt, replacements, skipUntil };
221
+ const temp = path_1.default.join(this.dir, `meta.json.${this.nonce}.tmp`);
222
+ try {
223
+ const handle = await this.filesystem.open(temp, 'wx', 0o600);
224
+ try {
225
+ await handle.writeFile(JSON.stringify(body));
226
+ }
227
+ finally {
228
+ await handle.close();
229
+ }
230
+ await this.filesystem.rename(temp, path_1.default.join(this.dir, 'meta.json'));
231
+ }
232
+ catch (error) {
233
+ await this.filesystem.rm(temp, { force: true }).catch(() => undefined);
234
+ throw error;
235
+ }
236
+ }
237
+ }
238
+ function defaultMeta() {
239
+ return { version: 1, databaseId: null, createdAt: null, syncOrigin: null, lastSyncedAt: null, replacements: [], skipUntil: null };
240
+ }
241
+ /** The stored meta; `'missing'` when there is no file; null when it is corrupt (not a regular file, unparseable, wrong version or wrong shape). */
242
+ async function readMeta(filesystem, metaPath) {
243
+ const stat = await lstatIfPresent(filesystem, metaPath);
244
+ if (stat === null)
245
+ return 'missing';
246
+ if (!stat.isFile())
247
+ return null;
248
+ let parsed;
249
+ try {
250
+ parsed = JSON.parse(await filesystem.readFile(metaPath, 'utf8'));
251
+ }
252
+ catch {
253
+ return null;
254
+ }
255
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
256
+ return null;
257
+ const candidate = parsed;
258
+ const isNullableString = (value) => value === null || typeof value === 'string';
259
+ const isNullableNumber = (value) => value === null || (typeof value === 'number' && Number.isFinite(value));
260
+ if (candidate.version !== 1
261
+ || !isNullableString(candidate.databaseId)
262
+ || !isNullableString(candidate.createdAt)
263
+ || !isNullableString(candidate.syncOrigin)
264
+ || !isNullableNumber(candidate.lastSyncedAt)
265
+ || !isNullableNumber(candidate.skipUntil)
266
+ || !Array.isArray(candidate.replacements)
267
+ || !candidate.replacements.every((when) => typeof when === 'number' && Number.isFinite(when))) {
268
+ return null;
269
+ }
270
+ // Validated above; extra keys are harmless because writeMeta writes only the documented ones.
271
+ return candidate;
272
+ }
273
+ /** True when this run now holds the lock; false when it is busy. Throws only for an unexpected filesystem error. */
274
+ async function takeLock(filesystem, dir, ours, now, processAlive) {
275
+ const lockPath = path_1.default.join(dir, 'lock');
276
+ if (await createLockFile(filesystem, lockPath, ours))
277
+ return true;
278
+ const judgement = await judgeExistingLock(filesystem, lockPath, ours.host, now, processAlive);
279
+ if (!judgement.stale)
280
+ return false;
281
+ return reclaimStaleLock(filesystem, dir, judgement.lock, ours, now);
282
+ }
283
+ /** Creates `lock` with `wx` and writes our record; false when a lock already exists. */
284
+ async function createLockFile(filesystem, lockPath, record) {
285
+ let handle;
286
+ try {
287
+ handle = await filesystem.open(lockPath, 'wx', 0o600);
288
+ }
289
+ catch (error) {
290
+ if (errorCode(error) === 'EEXIST')
291
+ return false;
292
+ throw error;
293
+ }
294
+ try {
295
+ try {
296
+ await handle.writeFile(JSON.stringify(record));
297
+ }
298
+ finally {
299
+ await handle.close();
300
+ }
301
+ }
302
+ catch (error) {
303
+ // A lock we created but could not fill is ours to remove; never leave an empty one behind.
304
+ await filesystem.unlink(lockPath).catch(() => undefined);
305
+ throw error;
306
+ }
307
+ return true;
308
+ }
309
+ async function judgeExistingLock(filesystem, lockPath, ourHost, now, processAlive) {
310
+ const stat = await lstatIfPresent(filesystem, lockPath);
311
+ // Gone between our `wx` and this read: another pull just released it. Busy this time.
312
+ if (stat === null)
313
+ return { stale: false };
314
+ const content = stat.isFile() ? await readIfPresent(filesystem, lockPath) : null;
315
+ const record = content === null ? null : parseLockRecord(content);
316
+ const oldEnough = now() - stat.mtimeMs > exports.REPLICA_CACHE_STALE_LOCK_MS;
317
+ if (record === null) {
318
+ return oldEnough ? { stale: true, lock: { kind: 'unreadable', dev: stat.dev, ino: stat.ino, mtimeMs: stat.mtimeMs, content } } : { stale: false };
319
+ }
320
+ if (record.host !== ourHost) {
321
+ return oldEnough ? { stale: true, lock: { kind: 'parsed', nonce: record.nonce } } : { stale: false };
322
+ }
323
+ return processAlive(record.pid) ? { stale: false } : { stale: true, lock: { kind: 'parsed', nonce: record.nonce } };
324
+ }
325
+ /**
326
+ * Replaces a stale lock under `lock.reclaim` (`wx`): re-read `lock`, confirm it is still the one
327
+ * judged stale, remove it, create ours with `wx`. Every loser answers busy.
328
+ */
329
+ async function reclaimStaleLock(filesystem, dir, judged, ours, now) {
330
+ const lockPath = path_1.default.join(dir, 'lock');
331
+ const reclaimPath = path_1.default.join(dir, 'lock.reclaim');
332
+ let reclaimHandle;
333
+ try {
334
+ reclaimHandle = await filesystem.open(reclaimPath, 'wx', 0o600);
335
+ }
336
+ catch (error) {
337
+ if (errorCode(error) !== 'EEXIST')
338
+ throw error;
339
+ const reclaimStat = await lstatIfPresent(filesystem, reclaimPath);
340
+ // A reclaim abandoned by a crashed pull: clear it for the next acquirer; busy this time.
341
+ if (reclaimStat !== null && now() - reclaimStat.mtimeMs > exports.REPLICA_CACHE_STALE_RECLAIM_MS) {
342
+ await filesystem.rm(reclaimPath, { force: true });
343
+ }
344
+ return false;
345
+ }
346
+ try {
347
+ await reclaimHandle.close();
348
+ if (!(await isSameStaleLock(filesystem, lockPath, judged)))
349
+ return false;
350
+ await filesystem.unlink(lockPath);
351
+ return await createLockFile(filesystem, lockPath, ours);
352
+ }
353
+ finally {
354
+ await filesystem.rm(reclaimPath, { force: true }).catch(() => undefined);
355
+ }
356
+ }
357
+ async function isSameStaleLock(filesystem, lockPath, judged) {
358
+ const stat = await lstatIfPresent(filesystem, lockPath);
359
+ if (stat === null)
360
+ return false;
361
+ const content = stat.isFile() ? await readIfPresent(filesystem, lockPath) : null;
362
+ const record = content === null ? null : parseLockRecord(content);
363
+ if (judged.kind === 'parsed')
364
+ return record !== null && record.nonce === judged.nonce;
365
+ return record === null
366
+ && stat.dev === judged.dev
367
+ && stat.ino === judged.ino
368
+ && stat.mtimeMs === judged.mtimeMs
369
+ && content === judged.content;
370
+ }
371
+ function parseLockRecord(content) {
372
+ let parsed;
373
+ try {
374
+ parsed = JSON.parse(content);
375
+ }
376
+ catch {
377
+ return null;
378
+ }
379
+ if (typeof parsed !== 'object' || parsed === null)
380
+ return null;
381
+ const candidate = parsed;
382
+ if (typeof candidate.pid !== 'number' || !Number.isInteger(candidate.pid) || candidate.pid <= 0
383
+ || typeof candidate.host !== 'string'
384
+ || typeof candidate.nonce !== 'string' || candidate.nonce === ''
385
+ || typeof candidate.at !== 'number') {
386
+ return null;
387
+ }
388
+ return { pid: candidate.pid, host: candidate.host, nonce: candidate.nonce, at: candidate.at };
389
+ }
390
+ /** `process.kill(pid, 0)`: alive unless it throws `ESRCH` (`EPERM` means alive, owned by someone else). */
391
+ function defaultProcessAlive(pid) {
392
+ try {
393
+ process.kill(pid, 0);
394
+ return true;
395
+ }
396
+ catch (error) {
397
+ return errorCode(error) !== 'ESRCH';
398
+ }
399
+ }
400
+ /** True when `candidate` is a real directory (never followed through a symlink) with anything inside it. */
401
+ async function isNonEmptyDirectory(filesystem, candidate) {
402
+ const stat = await lstatIfPresent(filesystem, candidate);
403
+ if (stat === null || !stat.isDirectory())
404
+ return false;
405
+ return (await filesystem.readdir(candidate)).length > 0;
406
+ }
407
+ async function lstatIfPresent(filesystem, candidate) {
408
+ try {
409
+ return await filesystem.lstat(candidate);
410
+ }
411
+ catch (error) {
412
+ if (isMissingPath(error))
413
+ return null;
414
+ throw error;
415
+ }
416
+ }
417
+ async function readIfPresent(filesystem, candidate) {
418
+ try {
419
+ return await filesystem.readFile(candidate, 'utf8');
420
+ }
421
+ catch (error) {
422
+ if (isMissingPath(error))
423
+ return null;
424
+ throw error;
425
+ }
426
+ }
427
+ function isMissingPath(error) {
428
+ return errorCode(error) === 'ENOENT';
429
+ }
430
+ function errorCode(error) {
431
+ return typeof error === 'object' && error !== null && 'code' in error ? String(error.code) : undefined;
432
+ }
@@ -28,9 +28,9 @@ exports.EXAMPLES_REF = void 0;
28
28
  * users. If solidactions-examples ever starts publishing tags in step with the
29
29
  * SDK, replace this with a derivation the way sdk-version.ts does.
30
30
  *
31
- * Currently: the merged solidactions-examples mainline of wave cli-agent-docs
32
- * (examples PR #37: manifest v3.37.0, function extras, source of truth, app
33
- * pages, preview fallback; cli#251, cli#253). It also still
31
+ * Currently: the merged solidactions-examples mainline of wave cli-duckdb
32
+ * (examples PR #38: init template SDK ^0.11.0 and the DuckDB file API in
33
+ * the skills; cli#244, cli#246). It also still
34
34
  * includes ex#34 "workspace-database + Drizzle example", which is what makes
35
35
  * `ai examples` able to install workspace-database-drizzle (the runnable
36
36
  * connect + drizzle-kit-migration example #140 exists to point people at).
@@ -38,4 +38,4 @@ exports.EXAMPLES_REF = void 0;
38
38
  * repin EXAMPLES_REF to the examples repo's merged mainline SHA and verify the
39
39
  * exact ref during the release ritual.
40
40
  */
41
- exports.EXAMPLES_REF = '24134f376885fd02c2633c1253b691524ee6a58e';
41
+ exports.EXAMPLES_REF = '82719cfc1ba8a147900d808a106537787fe1bb06';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@solidactions/cli",
3
- "version": "3.38.0",
3
+ "version": "3.40.0",
4
4
  "description": "SolidActions CLI - Deploy and manage workflow automation",
5
5
  "main": "dist/index.js",
6
6
  "bin": {
@@ -55,7 +55,7 @@
55
55
  "tar": "^7.5.22"
56
56
  },
57
57
  "devDependencies": {
58
- "@solidactions/sdk": "^0.10.0",
58
+ "@solidactions/sdk": "^0.11.1",
59
59
  "@types/archiver": "^8.0.0",
60
60
  "@types/fs-extra": "^11.0.0",
61
61
  "@types/js-yaml": "^4.0.9",