@akal/supaforge 0.0.0-stage → 0.0.31

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.
Files changed (99) hide show
  1. package/README.md +350 -2
  2. package/bin/dev.js +10 -0
  3. package/bin/run.js +18 -0
  4. package/dist/base-command.d.ts +134 -0
  5. package/dist/base-command.js +9 -0
  6. package/dist/base-command.js.map +1 -0
  7. package/dist/branch-C4ndfoj5.d.ts +58 -0
  8. package/dist/chunk-4OU7KO5Y.js +13 -0
  9. package/dist/chunk-4OU7KO5Y.js.map +1 -0
  10. package/dist/chunk-5QQBTLWO.js +642 -0
  11. package/dist/chunk-5QQBTLWO.js.map +1 -0
  12. package/dist/chunk-5Z3SAIQS.js +2807 -0
  13. package/dist/chunk-5Z3SAIQS.js.map +1 -0
  14. package/dist/chunk-6WAMNZLO.js +336 -0
  15. package/dist/chunk-6WAMNZLO.js.map +1 -0
  16. package/dist/chunk-BHYLBKYD.js +156 -0
  17. package/dist/chunk-BHYLBKYD.js.map +1 -0
  18. package/dist/chunk-BLKJWDTL.js +153 -0
  19. package/dist/chunk-BLKJWDTL.js.map +1 -0
  20. package/dist/chunk-DQQ5E563.js +64 -0
  21. package/dist/chunk-DQQ5E563.js.map +1 -0
  22. package/dist/chunk-G2DIPIYU.js +94 -0
  23. package/dist/chunk-G2DIPIYU.js.map +1 -0
  24. package/dist/chunk-H5MJ5DFX.js +16 -0
  25. package/dist/chunk-H5MJ5DFX.js.map +1 -0
  26. package/dist/chunk-KIFJGON5.js +248 -0
  27. package/dist/chunk-KIFJGON5.js.map +1 -0
  28. package/dist/chunk-LQXF65MC.js +240 -0
  29. package/dist/chunk-LQXF65MC.js.map +1 -0
  30. package/dist/chunk-NXRSAVRU.js +478 -0
  31. package/dist/chunk-NXRSAVRU.js.map +1 -0
  32. package/dist/chunk-PARSNTBD.js +837 -0
  33. package/dist/chunk-PARSNTBD.js.map +1 -0
  34. package/dist/chunk-RRMI5CZD.js +376 -0
  35. package/dist/chunk-RRMI5CZD.js.map +1 -0
  36. package/dist/chunk-SF3YA42C.js +506 -0
  37. package/dist/chunk-SF3YA42C.js.map +1 -0
  38. package/dist/chunk-TQJSQLWA.js +574 -0
  39. package/dist/chunk-TQJSQLWA.js.map +1 -0
  40. package/dist/chunk-VMTBLHN2.js +122 -0
  41. package/dist/chunk-VMTBLHN2.js.map +1 -0
  42. package/dist/chunk-VOXZWQ3N.js +948 -0
  43. package/dist/chunk-VOXZWQ3N.js.map +1 -0
  44. package/dist/chunk-X6V2GGDZ.js +333 -0
  45. package/dist/chunk-X6V2GGDZ.js.map +1 -0
  46. package/dist/chunk-XMYMIURR.js +552 -0
  47. package/dist/chunk-XMYMIURR.js.map +1 -0
  48. package/dist/chunk-YVDSR4GM.js +1264 -0
  49. package/dist/chunk-YVDSR4GM.js.map +1 -0
  50. package/dist/commands/clone.d.ts +66 -0
  51. package/dist/commands/clone.js +416 -0
  52. package/dist/commands/clone.js.map +1 -0
  53. package/dist/commands/diff.d.ts +65 -0
  54. package/dist/commands/diff.js +24 -0
  55. package/dist/commands/diff.js.map +1 -0
  56. package/dist/commands/help.d.ts +32 -0
  57. package/dist/commands/help.js +36 -0
  58. package/dist/commands/help.js.map +1 -0
  59. package/dist/commands/hukam.d.ts +13 -0
  60. package/dist/commands/hukam.js +29 -0
  61. package/dist/commands/hukam.js.map +1 -0
  62. package/dist/commands/init.d.ts +47 -0
  63. package/dist/commands/init.js +388 -0
  64. package/dist/commands/init.js.map +1 -0
  65. package/dist/commands/mcp.d.ts +13 -0
  66. package/dist/commands/mcp.js +44 -0
  67. package/dist/commands/mcp.js.map +1 -0
  68. package/dist/commands/migrate/baseline.d.ts +24 -0
  69. package/dist/commands/migrate/baseline.js +69 -0
  70. package/dist/commands/migrate/baseline.js.map +1 -0
  71. package/dist/commands/migrate/create.d.ts +36 -0
  72. package/dist/commands/migrate/create.js +128 -0
  73. package/dist/commands/migrate/create.js.map +1 -0
  74. package/dist/commands/migrate/list.d.ts +23 -0
  75. package/dist/commands/migrate/list.js +110 -0
  76. package/dist/commands/migrate/list.js.map +1 -0
  77. package/dist/commands/migrate/run.d.ts +61 -0
  78. package/dist/commands/migrate/run.js +19 -0
  79. package/dist/commands/migrate/run.js.map +1 -0
  80. package/dist/commands/report.d.ts +27 -0
  81. package/dist/commands/report.js +210 -0
  82. package/dist/commands/report.js.map +1 -0
  83. package/dist/commands/restore.d.ts +26 -0
  84. package/dist/commands/restore.js +268 -0
  85. package/dist/commands/restore.js.map +1 -0
  86. package/dist/commands/snapshot.d.ts +33 -0
  87. package/dist/commands/snapshot.js +251 -0
  88. package/dist/commands/snapshot.js.map +1 -0
  89. package/dist/commands/sync.d.ts +16 -0
  90. package/dist/commands/sync.js +39 -0
  91. package/dist/commands/sync.js.map +1 -0
  92. package/dist/config-CTbeRlJk.d.ts +134 -0
  93. package/dist/help.d.ts +28 -0
  94. package/dist/help.js +64 -0
  95. package/dist/help.js.map +1 -0
  96. package/dist/index.d.ts +493 -0
  97. package/dist/index.js +147 -0
  98. package/dist/index.js.map +1 -0
  99. package/package.json +74 -4
@@ -0,0 +1,251 @@
1
+ import {
2
+ backup,
3
+ listMigrationFiles
4
+ } from "../chunk-KIFJGON5.js";
5
+ import "../chunk-G2DIPIYU.js";
6
+ import {
7
+ renderTip
8
+ } from "../chunk-BLKJWDTL.js";
9
+ import {
10
+ BaseCommand
11
+ } from "../chunk-SF3YA42C.js";
12
+ import {
13
+ DEFAULT_KEEP_COUNT,
14
+ captureSnapshot,
15
+ formatSnapshotLayers,
16
+ listSnapshots,
17
+ pruneSnapshots
18
+ } from "../chunk-YVDSR4GM.js";
19
+ import "../chunk-DQQ5E563.js";
20
+ import "../chunk-X6V2GGDZ.js";
21
+ import {
22
+ bold,
23
+ cmd,
24
+ dim,
25
+ ok,
26
+ warn
27
+ } from "../chunk-6WAMNZLO.js";
28
+
29
+ // src/commands/snapshot.ts
30
+ import { Flags } from "@oclif/core";
31
+ var SNAPSHOT_LAYERS = [
32
+ "schema (tables, columns, indexes, constraints)",
33
+ "rls (row-level security policies)",
34
+ "edge-functions (via Management API)",
35
+ "storage (buckets + policies)",
36
+ "auth (config via Management API)",
37
+ "cron (pg_cron jobs)",
38
+ "data (reference tables from checks.data.tables)",
39
+ "webhooks (database webhook triggers)",
40
+ "extensions (installed Postgres extensions)"
41
+ ];
42
+ var Snapshot = class _Snapshot extends BaseCommand {
43
+ static description = "Capture a point-in-time snapshot of a Supabase environment";
44
+ static examples = [
45
+ "<%= config.bin %> snapshot",
46
+ "<%= config.bin %> snapshot --apply",
47
+ "<%= config.bin %> snapshot --env=production --apply",
48
+ "<%= config.bin %> snapshot --migration --apply",
49
+ '<%= config.bin %> snapshot --migration --apply --description="added profiles table"',
50
+ "<%= config.bin %> snapshot --list",
51
+ "<%= config.bin %> snapshot --prune",
52
+ "<%= config.bin %> snapshot --prune --keep=5 --apply",
53
+ "<%= config.bin %> snapshot --output=./backups --apply"
54
+ ];
55
+ static flags = {
56
+ env: Flags.string({
57
+ char: "e",
58
+ description: "Environment to snapshot (defaults to config source)"
59
+ }),
60
+ migration: Flags.boolean({
61
+ description: "Also generate an incremental migration diff against the previous snapshot",
62
+ default: false
63
+ }),
64
+ description: Flags.string({
65
+ char: "d",
66
+ description: "Human-readable description for the migration",
67
+ default: "auto-backup"
68
+ }),
69
+ list: Flags.boolean({
70
+ description: "List existing snapshots",
71
+ default: false
72
+ }),
73
+ prune: Flags.boolean({
74
+ description: `Delete old snapshots, keeping the most recent (default: ${DEFAULT_KEEP_COUNT})`,
75
+ default: false
76
+ }),
77
+ keep: Flags.integer({
78
+ description: "Number of snapshots to keep when pruning",
79
+ default: DEFAULT_KEEP_COUNT,
80
+ min: 1
81
+ }),
82
+ apply: Flags.boolean({
83
+ description: "Execute the snapshot (default: dry-run preview). Also required for --prune.",
84
+ default: false
85
+ }),
86
+ json: Flags.boolean({ description: "Output results as JSON" }),
87
+ output: Flags.string({
88
+ char: "o",
89
+ description: "Custom output directory for snapshot files (timestamp subfolder is created inside)"
90
+ })
91
+ };
92
+ async run() {
93
+ const { flags } = await this.parse(_Snapshot);
94
+ const config = await this.loadConfigOrFail();
95
+ if (flags.list) {
96
+ const snapshots = await listSnapshots();
97
+ if (snapshots.length === 0) {
98
+ this.log("No snapshots found.");
99
+ return;
100
+ }
101
+ if (flags.json) {
102
+ this.json(snapshots.map((s) => s.manifest));
103
+ return;
104
+ }
105
+ this.log(`
106
+ ${bold(`${snapshots.length} snapshot(s):`)}
107
+ `);
108
+ for (const { manifest } of snapshots) {
109
+ const layerCount = Object.values(manifest.layers).filter((l) => l.captured).length;
110
+ const itemCount = Object.values(manifest.layers).reduce((sum, l) => sum + l.itemCount, 0);
111
+ this.log(` ${bold(manifest.timestamp)} ${dim("env=")}${manifest.environment} ${dim("layers=")}${layerCount} ${dim("items=")}${itemCount}`);
112
+ }
113
+ this.log("");
114
+ this.log(renderTip({ command: "snapshot", snapshotList: true }));
115
+ return;
116
+ }
117
+ if (flags.prune) {
118
+ const keepCount = flags.keep;
119
+ const snapshots = await listSnapshots();
120
+ const deleteCount = Math.max(0, snapshots.length - keepCount);
121
+ if (deleteCount === 0) {
122
+ this.log(`
123
+ Nothing to prune \u2014 ${snapshots.length} snapshot(s), keeping ${keepCount}.
124
+ `);
125
+ return;
126
+ }
127
+ this.log(`
128
+ Prune: ${snapshots.length} snapshot(s) found, keeping ${keepCount}.`);
129
+ this.log(` ${deleteCount} snapshot(s) would be deleted:
130
+ `);
131
+ const toDelete = snapshots.slice(0, deleteCount);
132
+ for (const { manifest } of toDelete) {
133
+ this.log(` ${warn("\u2717")} ${manifest.timestamp} ${dim("env=")}${manifest.environment}`);
134
+ }
135
+ this.log("");
136
+ if (!flags.apply) {
137
+ this.log(` \u2192 Add ${cmd("--apply")} to delete these snapshots.
138
+ `);
139
+ return;
140
+ }
141
+ const result = await pruneSnapshots(keepCount);
142
+ if (flags.json) {
143
+ this.json(result);
144
+ return;
145
+ }
146
+ this.log(` Deleted ${result.deleted.length} snapshot(s), ${result.kept.length} remaining.`);
147
+ if (result.retainedForMigrations && result.retainedForMigrations.length > 0) {
148
+ this.log(` ${result.retainedForMigrations.length} kept beyond --keep: a migration names each as its parent.`);
149
+ }
150
+ this.log("");
151
+ return;
152
+ }
153
+ const { envName, env } = this.resolveEnv(config, flags.env);
154
+ if (!flags.json) {
155
+ const pre = this.createPreflight("Snapshot preflight checks").addDatabase("Database", envName, env.dbUrl);
156
+ await this.runPreflight(pre, "Snapshot");
157
+ }
158
+ if (!flags.apply) {
159
+ if (flags.json) {
160
+ this.json({ dryRun: true, environment: envName, migration: flags.migration });
161
+ return;
162
+ }
163
+ this.log(`
164
+ ${bold("Snapshot preview")} ${dim("(dry-run)")}
165
+ `);
166
+ this.log(` Environment: ${envName}`);
167
+ this.log(` Mode: ${flags.migration ? "snapshot + incremental migration" : "snapshot"}`);
168
+ this.log("");
169
+ this.log(" Layers that will be captured (when present):");
170
+ for (const layer of SNAPSHOT_LAYERS) {
171
+ this.log(` ${dim("\u2022")} ${layer}`);
172
+ }
173
+ this.log("");
174
+ this.log(` ${dim("Layers with no data (e.g. no cron, no storage) are skipped automatically.")}`);
175
+ this.log(`
176
+ \u2192 Add ${cmd("--apply")} to capture the snapshot.
177
+ `);
178
+ this.log(renderTip({ command: "snapshot", snapshotMigration: flags.migration, snapshotList: false }));
179
+ return;
180
+ }
181
+ if (flags.migration) {
182
+ this.log(`
183
+ Capturing snapshot of "${envName}" with migration...
184
+ `);
185
+ const result = await backup({
186
+ envName,
187
+ env,
188
+ config,
189
+ description: flags.description,
190
+ outputDir: flags.output
191
+ });
192
+ if (flags.json) {
193
+ this.json({
194
+ isBaseline: result.isBaseline,
195
+ snapshot: result.snapshot.manifest,
196
+ migration: result.migration,
197
+ migrationFile: result.migrationFile
198
+ });
199
+ return;
200
+ }
201
+ this.logSnapshotResult(result.snapshot.manifest);
202
+ this.log(` ${dim("Snapshot:")} ${result.snapshot.dir}`);
203
+ if (result.isBaseline) {
204
+ this.log(` ${dim("Type:")} baseline (first snapshot)`);
205
+ } else {
206
+ this.log(` ${dim("Type:")} incremental diff`);
207
+ }
208
+ if (result.migration) {
209
+ this.log(` ${dim("Migration:")} ${result.migrationFile}`);
210
+ this.log(` ${dim("Layers:")} ${result.migration.layers.join(", ")}`);
211
+ this.log(` ${dim("SQL up:")} ${result.migration.up.sql.length} statement(s)`);
212
+ this.log(` ${dim("API up:")} ${result.migration.up.api.length} action(s)`);
213
+ } else {
214
+ this.log(` ${dim("Migration:")} none (no changes detected)`);
215
+ }
216
+ this.log(`
217
+ ${ok("Snapshot + migration complete.")}
218
+ `);
219
+ this.log(renderTip({ command: "snapshot", snapshotMigration: true }));
220
+ return;
221
+ }
222
+ this.log(`
223
+ Capturing snapshot of "${envName}"...
224
+ `);
225
+ const snapshot = await captureSnapshot({ envName, env, config, outputDir: flags.output });
226
+ if (flags.json) {
227
+ this.json(snapshot.manifest);
228
+ return;
229
+ }
230
+ this.logSnapshotResult(snapshot.manifest);
231
+ this.log(`
232
+ ${dim("Snapshot saved to:")} ${snapshot.dir}`);
233
+ const existing = await listMigrationFiles();
234
+ if (existing.length > 0) {
235
+ this.log(` \u2192 Run with ${cmd("--migration")} to also generate an incremental diff.`);
236
+ } else {
237
+ this.log(` \u2192 Run with ${cmd("--migration")} to save a baseline migration.`);
238
+ }
239
+ this.log("");
240
+ this.log(renderTip({ command: "snapshot", snapshotMigration: false, snapshotList: false }));
241
+ }
242
+ logSnapshotResult(manifest) {
243
+ for (const line of formatSnapshotLayers(manifest)) {
244
+ this.log(` ${line}`);
245
+ }
246
+ }
247
+ };
248
+ export {
249
+ Snapshot as default
250
+ };
251
+ //# sourceMappingURL=snapshot.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../../src/commands/snapshot.ts"],"sourcesContent":["import { Flags } from '@oclif/core'\nimport { BaseCommand } from '../base-command.js'\nimport { captureSnapshot, listSnapshots, pruneSnapshots, formatSnapshotLayers, DEFAULT_KEEP_COUNT } from '../snapshot.js'\nimport { backup, listMigrationFiles } from '../migration.js'\nimport type { SnapshotManifest } from '../types/config.js'\nimport { ok, warn, dim, cmd, bold } from '../ui.js'\nimport { renderTip } from '../tips.js'\n\n/** Human-readable layer names captured by a snapshot, shown in the dry-run preview. */\nconst SNAPSHOT_LAYERS = [\n 'schema (tables, columns, indexes, constraints)',\n 'rls (row-level security policies)',\n 'edge-functions (via Management API)',\n 'storage (buckets + policies)',\n 'auth (config via Management API)',\n 'cron (pg_cron jobs)',\n 'data (reference tables from checks.data.tables)',\n 'webhooks (database webhook triggers)',\n 'extensions (installed Postgres extensions)',\n]\n\n/**\n * Capture and manage environment state snapshots.\n *\n * Default: dry-run preview of what would be captured (requires --apply)\n * --apply: actually capture the snapshot\n * --migration: also generate an incremental migration diff (was: backup)\n * --list: list existing snapshots\n * --prune: delete old snapshots\n */\nexport default class Snapshot extends BaseCommand {\n static override description = 'Capture a point-in-time snapshot of a Supabase environment'\n\n static override examples = [\n '<%= config.bin %> snapshot',\n '<%= config.bin %> snapshot --apply',\n '<%= config.bin %> snapshot --env=production --apply',\n '<%= config.bin %> snapshot --migration --apply',\n '<%= config.bin %> snapshot --migration --apply --description=\"added profiles table\"',\n '<%= config.bin %> snapshot --list',\n '<%= config.bin %> snapshot --prune',\n '<%= config.bin %> snapshot --prune --keep=5 --apply',\n '<%= config.bin %> snapshot --output=./backups --apply',\n ]\n\n static override flags = {\n env: Flags.string({\n char: 'e',\n description: 'Environment to snapshot (defaults to config source)',\n }),\n migration: Flags.boolean({\n description: 'Also generate an incremental migration diff against the previous snapshot',\n default: false,\n }),\n description: Flags.string({\n char: 'd',\n description: 'Human-readable description for the migration',\n default: 'auto-backup',\n }),\n list: Flags.boolean({\n description: 'List existing snapshots',\n default: false,\n }),\n prune: Flags.boolean({\n description: `Delete old snapshots, keeping the most recent (default: ${DEFAULT_KEEP_COUNT})`,\n default: false,\n }),\n keep: Flags.integer({\n description: 'Number of snapshots to keep when pruning',\n default: DEFAULT_KEEP_COUNT,\n min: 1,\n }),\n apply: Flags.boolean({\n description: 'Execute the snapshot (default: dry-run preview). Also required for --prune.',\n default: false,\n }),\n json: Flags.boolean({ description: 'Output results as JSON' }),\n output: Flags.string({\n char: 'o',\n description: 'Custom output directory for snapshot files (timestamp subfolder is created inside)',\n }),\n }\n\n async run(): Promise<void> {\n const { flags } = await this.parse(Snapshot)\n\n const config = await this.loadConfigOrFail()\n\n // ── List mode ────────────────────────────────────────────────────────────\n if (flags.list) {\n const snapshots = await listSnapshots()\n if (snapshots.length === 0) {\n this.log('No snapshots found.')\n return\n }\n if (flags.json) {\n this.json(snapshots.map(s => s.manifest))\n return\n }\n this.log(`\\n${bold(`${snapshots.length} snapshot(s):`)}\\n`)\n for (const { manifest } of snapshots) {\n const layerCount = Object.values(manifest.layers).filter(l => l.captured).length\n const itemCount = Object.values(manifest.layers).reduce((sum, l) => sum + l.itemCount, 0)\n this.log(` ${bold(manifest.timestamp)} ${dim('env=')}${manifest.environment} ${dim('layers=')}${layerCount} ${dim('items=')}${itemCount}`)\n }\n this.log('')\n this.log(renderTip({ command: 'snapshot', snapshotList: true }))\n return\n }\n\n // ── Prune mode ───────────────────────────────────────────────────────────\n if (flags.prune) {\n const keepCount = flags.keep\n const snapshots = await listSnapshots()\n const deleteCount = Math.max(0, snapshots.length - keepCount)\n\n if (deleteCount === 0) {\n this.log(`\\nNothing to prune — ${snapshots.length} snapshot(s), keeping ${keepCount}.\\n`)\n return\n }\n\n this.log(`\\nPrune: ${snapshots.length} snapshot(s) found, keeping ${keepCount}.`)\n this.log(` ${deleteCount} snapshot(s) would be deleted:\\n`)\n\n const toDelete = snapshots.slice(0, deleteCount)\n for (const { manifest } of toDelete) {\n this.log(` ${warn('✗')} ${manifest.timestamp} ${dim('env=')}${manifest.environment}`)\n }\n this.log('')\n\n if (!flags.apply) {\n this.log(` → Add ${cmd('--apply')} to delete these snapshots.\\n`)\n return\n }\n\n const result = await pruneSnapshots(keepCount)\n\n if (flags.json) {\n this.json(result)\n return\n }\n\n this.log(` Deleted ${result.deleted.length} snapshot(s), ${result.kept.length} remaining.`)\n if (result.retainedForMigrations && result.retainedForMigrations.length > 0) {\n // Kept past the budget on purpose: a migration names each of these as\n // its parent, and deleting one breaks that migration's chain (#92).\n this.log(` ${result.retainedForMigrations.length} kept beyond --keep: a migration names each as its parent.`)\n }\n this.log('')\n return\n }\n\n // ── Capture snapshot (with optional migration) ───────────────────────────\n const { envName, env } = this.resolveEnv(config, flags.env)\n\n // Preflight: verify database is reachable\n if (!flags.json) {\n const pre = this.createPreflight('Snapshot preflight checks')\n .addDatabase('Database', envName, env.dbUrl)\n await this.runPreflight(pre, 'Snapshot')\n }\n\n // ── Dry-run gate ─────────────────────────────────────────────────────────\n // Like clone / diff / restore, snapshot is a preview unless --apply is given.\n if (!flags.apply) {\n if (flags.json) {\n this.json({ dryRun: true, environment: envName, migration: flags.migration })\n return\n }\n this.log(`\\n ${bold('Snapshot preview')} ${dim('(dry-run)')}\\n`)\n this.log(` Environment: ${envName}`)\n this.log(` Mode: ${flags.migration ? 'snapshot + incremental migration' : 'snapshot'}`)\n this.log('')\n this.log(' Layers that will be captured (when present):')\n for (const layer of SNAPSHOT_LAYERS) {\n this.log(` ${dim('•')} ${layer}`)\n }\n this.log('')\n this.log(` ${dim('Layers with no data (e.g. no cron, no storage) are skipped automatically.')}`)\n this.log(`\\n → Add ${cmd('--apply')} to capture the snapshot.\\n`)\n this.log(renderTip({ command: 'snapshot', snapshotMigration: flags.migration, snapshotList: false }))\n return\n }\n\n if (flags.migration) {\n // Capture + generate migration (was: backup command)\n this.log(`\\nCapturing snapshot of \"${envName}\" with migration...\\n`)\n\n const result = await backup({\n envName,\n env,\n config,\n description: flags.description,\n outputDir: flags.output,\n })\n\n if (flags.json) {\n this.json({\n isBaseline: result.isBaseline,\n snapshot: result.snapshot.manifest,\n migration: result.migration,\n migrationFile: result.migrationFile,\n })\n return\n }\n\n this.logSnapshotResult(result.snapshot.manifest)\n this.log(` ${dim('Snapshot:')} ${result.snapshot.dir}`)\n\n if (result.isBaseline) {\n this.log(` ${dim('Type:')} baseline (first snapshot)`)\n } else {\n this.log(` ${dim('Type:')} incremental diff`)\n }\n\n if (result.migration) {\n this.log(` ${dim('Migration:')} ${result.migrationFile}`)\n this.log(` ${dim('Layers:')} ${result.migration.layers.join(', ')}`)\n this.log(` ${dim('SQL up:')} ${result.migration.up.sql.length} statement(s)`)\n this.log(` ${dim('API up:')} ${result.migration.up.api.length} action(s)`)\n } else {\n this.log(` ${dim('Migration:')} none (no changes detected)`)\n }\n\n this.log(`\\n ${ok('Snapshot + migration complete.')}\\n`)\n this.log(renderTip({ command: 'snapshot', snapshotMigration: true }))\n return\n }\n\n // Plain snapshot — just capture, no dry-run gate\n this.log(`\\nCapturing snapshot of \"${envName}\"...\\n`)\n\n const snapshot = await captureSnapshot({ envName, env, config, outputDir: flags.output })\n\n if (flags.json) {\n this.json(snapshot.manifest)\n return\n }\n\n this.logSnapshotResult(snapshot.manifest)\n this.log(`\\n ${dim('Snapshot saved to:')} ${snapshot.dir}`)\n\n // Show migration hint\n const existing = await listMigrationFiles()\n if (existing.length > 0) {\n this.log(` → Run with ${cmd('--migration')} to also generate an incremental diff.`)\n } else {\n this.log(` → Run with ${cmd('--migration')} to save a baseline migration.`)\n }\n this.log('')\n this.log(renderTip({ command: 'snapshot', snapshotMigration: false, snapshotList: false }))\n }\n\n private logSnapshotResult(manifest: SnapshotManifest): void {\n for (const line of formatSnapshotLayers(manifest)) {\n this.log(` ${line}`)\n }\n }\n}\n"],"mappings":"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","names":[]}
@@ -0,0 +1,16 @@
1
+ import Diff from './diff.js';
2
+ import '@oclif/core/interfaces';
3
+ import '../base-command.js';
4
+ import '@oclif/core';
5
+ import '../config-CTbeRlJk.js';
6
+
7
+ /**
8
+ * Alias for `diff --apply` — detect and fix drift in one step.
9
+ */
10
+ declare class Sync extends Diff {
11
+ static description: string;
12
+ static examples: string[];
13
+ run(): Promise<void>;
14
+ }
15
+
16
+ export { Sync as default };
@@ -0,0 +1,39 @@
1
+ import {
2
+ Diff
3
+ } from "../chunk-XMYMIURR.js";
4
+ import "../chunk-4OU7KO5Y.js";
5
+ import "../chunk-LQXF65MC.js";
6
+ import "../chunk-5Z3SAIQS.js";
7
+ import "../chunk-TQJSQLWA.js";
8
+ import "../chunk-H5MJ5DFX.js";
9
+ import "../chunk-VOXZWQ3N.js";
10
+ import "../chunk-RRMI5CZD.js";
11
+ import "../chunk-G2DIPIYU.js";
12
+ import "../chunk-BLKJWDTL.js";
13
+ import "../chunk-SF3YA42C.js";
14
+ import "../chunk-5QQBTLWO.js";
15
+ import "../chunk-YVDSR4GM.js";
16
+ import "../chunk-DQQ5E563.js";
17
+ import "../chunk-X6V2GGDZ.js";
18
+ import "../chunk-6WAMNZLO.js";
19
+
20
+ // src/commands/sync.ts
21
+ var Sync = class extends Diff {
22
+ static description = "Detect and fix drift (alias for diff --apply)";
23
+ static examples = [
24
+ "<%= config.bin %> sync",
25
+ "<%= config.bin %> sync --check=rls",
26
+ "<%= config.bin %> sync --source=staging --target=production"
27
+ ];
28
+ async run() {
29
+ const argv = [...this.argv];
30
+ if (!argv.includes("--apply")) {
31
+ argv.push("--apply");
32
+ }
33
+ await Diff.run(argv, this.config);
34
+ }
35
+ };
36
+ export {
37
+ Sync as default
38
+ };
39
+ //# sourceMappingURL=sync.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../../src/commands/sync.ts"],"sourcesContent":["import Diff from './diff.js'\n\n/**\n * Alias for `diff --apply` — detect and fix drift in one step.\n */\nexport default class Sync extends Diff {\n static override description = 'Detect and fix drift (alias for diff --apply)'\n\n static override examples = [\n '<%= config.bin %> sync',\n '<%= config.bin %> sync --check=rls',\n '<%= config.bin %> sync --source=staging --target=production',\n ]\n\n async run(): Promise<void> {\n // Inject --apply before delegating to Diff\n const argv = [...this.argv]\n if (!argv.includes('--apply')) {\n argv.push('--apply')\n }\n\n // Re-parse with injected --apply flag\n await Diff.run(argv, this.config)\n }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAKA,IAAqB,OAArB,cAAkC,KAAK;AAAA,EACrC,OAAgB,cAAc;AAAA,EAE9B,OAAgB,WAAW;AAAA,IACzB;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EAEA,MAAM,MAAqB;AAEzB,UAAM,OAAO,CAAC,GAAG,KAAK,IAAI;AAC1B,QAAI,CAAC,KAAK,SAAS,SAAS,GAAG;AAC7B,WAAK,KAAK,SAAS;AAAA,IACrB;AAGA,UAAM,KAAK,IAAI,MAAM,KAAK,MAAM;AAAA,EAClC;AACF;","names":[]}
@@ -0,0 +1,134 @@
1
+ type MigrationsMode = 'auto' | 'warn' | 'ignore';
2
+ /**
3
+ * Per-environment check overrides.
4
+ *
5
+ * A check can be fine against a fast local clone and hopeless against a
6
+ * remote environment over a VPN, so a single top-level setting is too coarse
7
+ * (issue #29). These apply on top of the top-level `checks` config.
8
+ */
9
+ interface EnvironmentChecksConfig {
10
+ /** Checks to skip when this environment is the target. Unioned with the top-level list. */
11
+ exclude?: string[];
12
+ /** Schema-check overrides for this environment. */
13
+ schema?: {
14
+ /** Seconds before the schema/data diff is abandoned. Overrides the global default. */
15
+ timeout?: number;
16
+ };
17
+ }
18
+ interface EnvironmentConfig {
19
+ dbUrl: string;
20
+ /** Check overrides applied when this environment is the diff target. */
21
+ checks?: EnvironmentChecksConfig;
22
+ projectRef?: string;
23
+ /** Personal access token for Supabase Management API (auth config, edge functions). */
24
+ accessToken?: string;
25
+ /** Base URL for self-hosted Supabase API gateway (e.g. http://localhost:54321). Overrides projectRef-based URL construction. */
26
+ apiUrl?: string;
27
+ /**
28
+ * Base URL of this environment's Supabase Studio, e.g. http://localhost:3000.
29
+ *
30
+ * Self-hosted Studio serves the same functions API shape as the hosted
31
+ * Management API, at /api/v1/projects/{ref}/functions. It is NOT behind the
32
+ * Kong gateway that `apiUrl` points at, which is why it needs its own field.
33
+ */
34
+ studioUrl?: string;
35
+ /**
36
+ * Directory holding this environment's Edge Functions, one subdirectory per
37
+ * function (the layout `supabase functions` uses, and the layout self-hosted
38
+ * edge-runtime mounts).
39
+ *
40
+ * A fallback for when Studio is not reachable — `studioUrl` is preferred
41
+ * because it works remotely and needs no filesystem access.
42
+ */
43
+ functionsPath?: string;
44
+ }
45
+ interface ChecksConfig {
46
+ /**
47
+ * Only compare these tables in the schema and data layers. Supports
48
+ * @dbdiff/cli globs (`billing_*`). Undefined means all tables.
49
+ *
50
+ * The `--tables` flag overrides this rather than merging with it: asking for
51
+ * one table on the command line must not be widened by a broader list in
52
+ * config (issue #43).
53
+ */
54
+ tables?: string[];
55
+ /**
56
+ * Never compare these tables. Applied after `tables`, and unioned with the
57
+ * `--exclude-tables` flag — an exclusion is a safety rail, so both sources
58
+ * excluding more is never the surprising direction.
59
+ */
60
+ excludeTables?: string[];
61
+ data?: {
62
+ tables: string[];
63
+ };
64
+ migrations?: {
65
+ dir?: string;
66
+ /**
67
+ * How to report local migration files with no row in schema_migrations.
68
+ *
69
+ * - `auto` (default) — if the tracking table is empty but local files
70
+ * exist, report one INFO noting an untracked migration workflow rather
71
+ * than a warning per file. Otherwise warn per file as usual.
72
+ * - `warn` — always warn per file, even when nothing is tracked.
73
+ * - `ignore` — report nothing from this check at all.
74
+ */
75
+ mode?: MigrationsMode;
76
+ };
77
+ /** Checks to always skip, regardless of CLI flags. Useful in config for clone environments. */
78
+ exclude?: string[];
79
+ }
80
+ interface SupaForgeConfig {
81
+ environments: Record<string, EnvironmentConfig>;
82
+ source?: string;
83
+ target?: string;
84
+ ignoreSchemas?: string[];
85
+ checks?: ChecksConfig;
86
+ }
87
+ interface SnapshotLayerInfo {
88
+ captured: boolean;
89
+ file: string;
90
+ /** Number of items captured (e.g. policies, buckets, jobs). -1 if not applicable. */
91
+ itemCount: number;
92
+ /** Error message if the layer failed to capture. */
93
+ error?: string;
94
+ /** Human-readable reason the layer was skipped (when captured is false and there is no error). */
95
+ skipReason?: string;
96
+ /**
97
+ * A companion file holding replayable SQL, when the layer's own `file` is
98
+ * not replayable. The schema layer is captured as introspection JSON for
99
+ * diffing, so it also writes `schema.sql` for `restore` (issue #80).
100
+ */
101
+ sqlFile?: string;
102
+ /** Why `sqlFile` is absent, when it could not be produced. */
103
+ sqlSkipReason?: string;
104
+ }
105
+ interface SnapshotManifest {
106
+ version: 1;
107
+ timestamp: string;
108
+ environment: string;
109
+ projectRef?: string;
110
+ layers: Record<string, SnapshotLayerInfo>;
111
+ }
112
+ interface MigrationAction {
113
+ method: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
114
+ /** Relative API path (e.g. /v1/projects/{ref}/config/auth). Ref is substituted at apply time. */
115
+ path: string;
116
+ body?: unknown;
117
+ label: string;
118
+ }
119
+ interface MigrationFile {
120
+ version: string;
121
+ description: string;
122
+ parent: string | null;
123
+ layers: string[];
124
+ up: {
125
+ sql: string[];
126
+ api: MigrationAction[];
127
+ };
128
+ down: {
129
+ sql: string[];
130
+ api: MigrationAction[];
131
+ };
132
+ }
133
+
134
+ export type { ChecksConfig as C, EnvironmentConfig as E, MigrationFile as M, SupaForgeConfig as S, SnapshotManifest as a, MigrationAction as b, SnapshotLayerInfo as c };
package/dist/help.d.ts ADDED
@@ -0,0 +1,28 @@
1
+ import { Help, Command } from '@oclif/core';
2
+
3
+ /**
4
+ * Environment variables a command reads, rendered as their own help section.
5
+ *
6
+ * These were documented only in the README, and `--help` is where users look
7
+ * first — especially for `diff`, whose behaviour they change (issue #40).
8
+ * Declared as a static on the command so the list sits next to the flags it
9
+ * complements rather than in a table someone has to remember to update.
10
+ */
11
+ interface CommandWithEnvVars {
12
+ envVars?: ReadonlyArray<{
13
+ name: string;
14
+ description: string;
15
+ }>;
16
+ }
17
+ declare class CustomHelp extends Help {
18
+ /** Append an ENVIRONMENT VARIABLES section to commands that declare one. */
19
+ protected formatCommand(command: Command.Loadable): string;
20
+ protected get sortedCommands(): Command.Loadable[];
21
+ /**
22
+ * Render only COMMANDS (no separate TOPICS section).
23
+ * Render only COMMANDS (no separate TOPICS section).
24
+ */
25
+ protected showRootHelp(): Promise<void>;
26
+ }
27
+
28
+ export { type CommandWithEnvVars, CustomHelp as default };
package/dist/help.js ADDED
@@ -0,0 +1,64 @@
1
+ // src/help.ts
2
+ import { Help } from "@oclif/core";
3
+ function envVarsOf(command) {
4
+ const declared = command.envVars;
5
+ return Array.isArray(declared) && declared.length > 0 ? declared : void 0;
6
+ }
7
+ var ORDER = [
8
+ "init",
9
+ "diff",
10
+ "sync",
11
+ "snapshot",
12
+ "clone",
13
+ "restore",
14
+ "migrate",
15
+ "report",
16
+ "mcp",
17
+ "hukam",
18
+ "help"
19
+ ];
20
+ var CustomHelp = class extends Help {
21
+ /** Append an ENVIRONMENT VARIABLES section to commands that declare one. */
22
+ formatCommand(command) {
23
+ const base = super.formatCommand(command);
24
+ const envVars = envVarsOf(command);
25
+ if (!envVars) return base;
26
+ const width = Math.max(...envVars.map((v) => v.name.length));
27
+ const rows = envVars.map((v) => ` ${v.name.padEnd(width)} ${v.description}`);
28
+ return [base, "", "ENVIRONMENT VARIABLES", ...rows].join("\n");
29
+ }
30
+ get sortedCommands() {
31
+ const sorted = super.sortedCommands;
32
+ const ordered = ORDER.map((id) => sorted.find((c) => c.id === id)).filter((c) => c !== void 0);
33
+ const rest = sorted.filter((c) => !ORDER.includes(c.id));
34
+ return [...ordered, ...rest];
35
+ }
36
+ /**
37
+ * Render only COMMANDS (no separate TOPICS section).
38
+ * Render only COMMANDS (no separate TOPICS section).
39
+ */
40
+ async showRootHelp() {
41
+ const state = this.config.pjson?.oclif?.state;
42
+ if (state) {
43
+ this.log(state === "deprecated" ? `${this.config.bin} is deprecated` : `${this.config.bin} is in ${state}.
44
+ `);
45
+ }
46
+ this.log(this.formatRoot());
47
+ this.log("");
48
+ const rootCommands = this.sortedCommands.filter((c) => c.id && !c.id.includes(":"));
49
+ const rootTopics = this.sortedTopics.filter((t) => !t.name.includes(":"));
50
+ const topicAsCommand = rootTopics.filter((t) => !rootCommands.some((c) => c.id === t.name)).map((t) => ({ id: t.name, summary: t.description ?? "" }));
51
+ const all = [...rootCommands, ...topicAsCommand];
52
+ const ordered = ORDER.map((id) => all.find((c) => c.id === id)).filter((c) => c !== void 0);
53
+ const rest = all.filter((c) => !ORDER.includes(c.id));
54
+ const merged = [...ordered, ...rest];
55
+ if (merged.length > 0) {
56
+ this.log(this.formatCommands(merged));
57
+ this.log("");
58
+ }
59
+ }
60
+ };
61
+ export {
62
+ CustomHelp as default
63
+ };
64
+ //# sourceMappingURL=help.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/help.ts"],"sourcesContent":["import { Help, type Command, type Interfaces } from '@oclif/core'\n\n/**\n * Environment variables a command reads, rendered as their own help section.\n *\n * These were documented only in the README, and `--help` is where users look\n * first — especially for `diff`, whose behaviour they change (issue #40).\n * Declared as a static on the command so the list sits next to the flags it\n * complements rather than in a table someone has to remember to update.\n */\nexport interface CommandWithEnvVars {\n envVars?: ReadonlyArray<{ name: string; description: string }>\n}\n\nfunction envVarsOf(command: Command.Loadable): CommandWithEnvVars['envVars'] {\n const declared = (command as unknown as CommandWithEnvVars).envVars\n return Array.isArray(declared) && declared.length > 0 ? declared : undefined\n}\n\n/**\n * Desired command order — matches the natural workflow:\n * setup → detect → snapshot → clone → restore → migrate, then the tools.\n *\n * Everything is named rather than only the first few: an unlisted command falls\n * to the alphabetical tail, which is how `migrate` — a topic of four\n * commands — ended up printed after `report` and `mcp`, and `help` in the\n * middle of the workflow (issue #97).\n */\nconst ORDER = [\n 'init',\n 'diff',\n 'sync',\n 'snapshot',\n 'clone',\n 'restore',\n 'migrate',\n 'report',\n 'mcp',\n 'hukam',\n 'help',\n]\n\nexport default class CustomHelp extends Help {\n /** Append an ENVIRONMENT VARIABLES section to commands that declare one. */\n protected override formatCommand(command: Command.Loadable): string {\n const base = super.formatCommand(command)\n const envVars = envVarsOf(command)\n if (!envVars) return base\n\n const width = Math.max(...envVars.map(v => v.name.length))\n const rows = envVars.map(v => ` ${v.name.padEnd(width)} ${v.description}`)\n return [base, '', 'ENVIRONMENT VARIABLES', ...rows].join('\\n')\n }\n\n protected override get sortedCommands(): Command.Loadable[] {\n const sorted = super.sortedCommands\n const ordered = ORDER\n .map((id) => sorted.find((c) => c.id === id))\n .filter((c): c is Command.Loadable => c !== undefined)\n const rest = sorted.filter((c) => !ORDER.includes(c.id))\n return [...ordered, ...rest]\n }\n\n /**\n * Render only COMMANDS (no separate TOPICS section).\n * Render only COMMANDS (no separate TOPICS section).\n */\n protected override async showRootHelp(): Promise<void> {\n const state = this.config.pjson?.oclif?.state as string | undefined\n if (state) {\n this.log(state === 'deprecated' ? `${this.config.bin} is deprecated` : `${this.config.bin} is in ${state}.\\n`)\n }\n\n this.log(this.formatRoot())\n this.log('')\n\n // Merge topics into the commands list so everything appears in one section.\n const rootCommands = this.sortedCommands.filter((c) => c.id && !c.id.includes(':'))\n const rootTopics = this.sortedTopics.filter((t) => !t.name.includes(':'))\n\n // Build topic entries that look like commands (id + description).\n const topicAsCommand = rootTopics\n .filter((t) => !rootCommands.some((c) => c.id === t.name))\n .map((t) => ({ id: t.name, summary: t.description ?? '' }) as unknown as Command.Loadable)\n\n // Merge and re-sort by ORDER\n const all = [...rootCommands, ...topicAsCommand]\n const ordered = ORDER\n .map((id) => all.find((c) => c.id === id))\n .filter((c): c is Command.Loadable => c !== undefined)\n const rest = all.filter((c) => !ORDER.includes(c.id))\n const merged = [...ordered, ...rest]\n\n if (merged.length > 0) {\n this.log(this.formatCommands(merged))\n this.log('')\n }\n }\n}\n"],"mappings":";AAAA,SAAS,YAA2C;AAcpD,SAAS,UAAU,SAA0D;AAC3E,QAAM,WAAY,QAA0C;AAC5D,SAAO,MAAM,QAAQ,QAAQ,KAAK,SAAS,SAAS,IAAI,WAAW;AACrE;AAWA,IAAM,QAAQ;AAAA,EACZ;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,IAAqB,aAArB,cAAwC,KAAK;AAAA;AAAA,EAExB,cAAc,SAAmC;AAClE,UAAM,OAAO,MAAM,cAAc,OAAO;AACxC,UAAM,UAAU,UAAU,OAAO;AACjC,QAAI,CAAC,QAAS,QAAO;AAErB,UAAM,QAAQ,KAAK,IAAI,GAAG,QAAQ,IAAI,OAAK,EAAE,KAAK,MAAM,CAAC;AACzD,UAAM,OAAO,QAAQ,IAAI,OAAK,KAAK,EAAE,KAAK,OAAO,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE;AAC3E,WAAO,CAAC,MAAM,IAAI,yBAAyB,GAAG,IAAI,EAAE,KAAK,IAAI;AAAA,EAC/D;AAAA,EAEA,IAAuB,iBAAqC;AAC1D,UAAM,SAAS,MAAM;AACrB,UAAM,UAAU,MACb,IAAI,CAAC,OAAO,OAAO,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EAC3C,OAAO,CAAC,MAA6B,MAAM,MAAS;AACvD,UAAM,OAAO,OAAO,OAAO,CAAC,MAAM,CAAC,MAAM,SAAS,EAAE,EAAE,CAAC;AACvD,WAAO,CAAC,GAAG,SAAS,GAAG,IAAI;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAyB,eAA8B;AACrD,UAAM,QAAQ,KAAK,OAAO,OAAO,OAAO;AACxC,QAAI,OAAO;AACT,WAAK,IAAI,UAAU,eAAe,GAAG,KAAK,OAAO,GAAG,mBAAmB,GAAG,KAAK,OAAO,GAAG,UAAU,KAAK;AAAA,CAAK;AAAA,IAC/G;AAEA,SAAK,IAAI,KAAK,WAAW,CAAC;AAC1B,SAAK,IAAI,EAAE;AAGX,UAAM,eAAe,KAAK,eAAe,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,SAAS,GAAG,CAAC;AAClF,UAAM,aAAa,KAAK,aAAa,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,SAAS,GAAG,CAAC;AAGxE,UAAM,iBAAiB,WACpB,OAAO,CAAC,MAAM,CAAC,aAAa,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,EACxD,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,EAAE,eAAe,GAAG,EAAiC;AAG3F,UAAM,MAAM,CAAC,GAAG,cAAc,GAAG,cAAc;AAC/C,UAAM,UAAU,MACb,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EACxC,OAAO,CAAC,MAA6B,MAAM,MAAS;AACvD,UAAM,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,SAAS,EAAE,EAAE,CAAC;AACpD,UAAM,SAAS,CAAC,GAAG,SAAS,GAAG,IAAI;AAEnC,QAAI,OAAO,SAAS,GAAG;AACrB,WAAK,IAAI,KAAK,eAAe,MAAM,CAAC;AACpC,WAAK,IAAI,EAAE;AAAA,IACb;AAAA,EACF;AACF;","names":[]}