@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/README.md +15 -5
- package/dist/command-manifest.json +29 -4
- package/dist/commands/database-export.js +4 -2
- package/dist/commands/database.js +615 -49
- package/dist/index.js +19 -6
- package/dist/utils/database-kind-refusal.js +27 -0
- package/dist/utils/database-pull-guidance.js +20 -0
- package/dist/utils/database-replica-cache.js +432 -0
- package/dist/utils/examples-ref.js +4 -4
- package/package.json +2 -2
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
|
-
|
|
291
|
-
straight to createDatabaseClient(), or to @libsql/client /
|
|
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>', '
|
|
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
|
-
.
|
|
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-
|
|
32
|
-
* (examples PR #
|
|
33
|
-
*
|
|
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 = '
|
|
41
|
+
exports.EXAMPLES_REF = '82719cfc1ba8a147900d808a106537787fe1bb06';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@solidactions/cli",
|
|
3
|
-
"version": "3.
|
|
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.
|
|
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",
|