@auscera/design-labs 0.1.0 → 0.1.1

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.
@@ -7,7 +7,7 @@ description: Install Design Labs into Next.js projects, snapshot landing or dash
7
7
 
8
8
  ## Install
9
9
 
10
- Inspect host instructions and workspace layout. Run `node <Design-Labs>/scripts/install.mjs <host>`; it detects monorepos and installs only the empty workspace. Install dependencies with the host package manager. Do not replace existing Labs automatically. Existing installations require a verified backup and migration of platform files only, retaining source archives and routes. Do not deploy or publish.
10
+ Inspect host instructions and workspace layout. From the host project root run `pnpm dlx @auscera/design-labs`; it detects monorepos and installs only the empty workspace. Install dependencies with the host package manager. Do not replace existing Labs automatically. Ask which frontend to use when the choice is ambiguous. Report unsupported setups and stop rather than changing preserved source. Do not deploy or publish.
11
11
 
12
12
  ## Setup and version workflow
13
13
 
@@ -29,7 +29,7 @@ Update task.md and walkthrough.md after verified work. Do not claim a screenshot
29
29
 
30
30
  ## /update and /fix
31
31
 
32
- Obtain a reviewed release checkout (local owner repository or pinned GitHub ref). Stop the installed Lab before updating. Run `node <release>/scripts/update.mjs plan <installed-lab>` (or `fix` to audit/repair). Review changed platform files and local conflicts, then `apply <installed-lab> <token>`. Only use `--accept-local` after reviewing deliberate overwrites. The updater backs up source and metadata, updates allowlisted platform files, preserves preview route groups and versions, and migrates old folders with hash checks. Reinstall dependencies, run types/build and browser tests before accepting. On failure use `rollback <installed-lab> <backup>`. Package upgrades may require agent compatibility resolution; never silently downgrade or remove project-specific dependencies.
32
+ Stop the installed Lab before updating. Choose a published, exact release version and run `pnpm dlx @auscera/design-labs@VERSION update plan /absolute/path/to/design-lab`. Review all changes, conflicts and dependency requirements. Apply with the same version and current token: `pnpm dlx @auscera/design-labs@VERSION update apply /absolute/path/to/design-lab TOKEN`. Only use `--accept-local` after reviewing deliberate overwrites. The updater backs up before changing managed platform files; it preserves local package settings, source, adapters, annotations, configuration and environment files. Resolve dependency requirements explicitly, then run types, build and browser checks. On failure, use the same pinned package with `update rollback /absolute/path/to/design-lab /absolute/path/to/backup`. Updates do not transfer source into the host project. The update command is available only once a release containing it is published; it is not present in 0.1.0.
33
33
 
34
34
  Installed source layout is `versions/landing/<version>/source` and `versions/dashboard/<version>/source`. Production is an approved version identity. IDs and existing preview URLs remain stable across folder migrations. Existing source apps are touched only by the reviewed source-transfer workflow.
35
35
 
package/package.json CHANGED
@@ -1,7 +1,11 @@
1
1
  {
2
2
  "name": "@auscera/design-labs",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "type": "module",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/delightc123/Design-Labs.git"
8
+ },
5
9
  "bin": {
6
10
  "design-labs-install": "scripts/install.mjs"
7
11
  },
@@ -2,7 +2,7 @@
2
2
  import fs from "node:fs";
3
3
  import path from "node:path";
4
4
  import { fileURLToPath } from "node:url";
5
- import { plan } from "./update.mjs";
5
+ import { plan, runUpdate } from "./update.mjs";
6
6
  const product = path.resolve(
7
7
  path.dirname(fileURLToPath(import.meta.url)),
8
8
  "..",
@@ -56,10 +56,14 @@ if (
56
56
  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
57
57
  ) {
58
58
  try {
59
+ if (process.argv[2] === "update") {
60
+ console.log(JSON.stringify(runUpdate(process.argv.slice(3)), null, 2));
61
+ } else {
59
62
  console.log(install(process.argv[2] || process.cwd()));
60
63
  console.log(
61
64
  "Read the installed AGENTS.md and skill, install dependencies using the target project's package manager, then run pnpm dev from the installed Lab. Prepare snapshots and previews as described in the skill.",
62
65
  );
66
+ }
63
67
  } catch (e) {
64
68
  console.error(e.message);
65
69
  process.exitCode = 1;
@@ -1,204 +1,155 @@
1
1
  #!/usr/bin/env node
2
- import fs from "node:fs";
3
- import path from "node:path";
4
- import crypto from "node:crypto";
5
- import { fileURLToPath } from "node:url";
6
- import { migrate } from "../apps/workspace/scripts/migrate.mjs";
7
- const product = path.resolve(
8
- path.dirname(fileURLToPath(import.meta.url)),
9
- "..",
10
- );
11
- const managed = [
12
- "app/(lab)",
13
- "app/api/versions",
14
- "app/api/annotations",
15
- "lib",
16
- "public/preview-bridge.js",
17
- "components",
18
- "scripts",
19
- "public/brand",
20
- "public/favicon.ico",
21
- "public/apple-touch-icon.png",
22
- "public/site.webmanifest",
23
- "public/icon-192.png",
24
- "public/icon-512.png",
25
- "AGENTS.md",
26
- ".skills",
27
- ];
28
- function list(dir, rel = "") {
29
- return fs
30
- .readdirSync(dir, { withFileTypes: true })
31
- .flatMap((e) =>
32
- e.isDirectory()
33
- ? list(path.join(dir, e.name), rel + e.name + "/")
34
- : [rel + e.name],
35
- );
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import crypto from 'node:crypto';
5
+ import { fileURLToPath } from 'node:url';
6
+ import { hashes, fingerprint } from '../apps/workspace/scripts/lab.mjs';
7
+
8
+ const product = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
9
+ const managed = ['app/(lab)', 'app/api/versions', 'app/api/annotations', 'lib', 'public/preview-bridge.js', 'components', 'scripts', 'public/brand', 'public/favicon.ico', 'public/apple-touch-icon.png', 'public/site.webmanifest', 'public/icon-192.png', 'public/icon-512.png', 'AGENTS.md', '.skills'];
10
+ const hash = p => fs.existsSync(p) ? crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex') : null;
11
+ const backupDir = target => path.join(path.dirname(target), '.design-labs-backups');
12
+ const pendingFile = target => path.join(backupDir(target), path.basename(target) + '.pending.json');
13
+
14
+ // Refuse symlinks in each managed path, including its parent directories.
15
+ function safePath(root, relative) {
16
+ let current = root;
17
+ for (const part of relative.split('/')) {
18
+ current = path.join(current, part);
19
+ try { if (fs.lstatSync(current).isSymbolicLink()) throw Error(`Symlink in update path: ${current}`); }
20
+ catch (error) { if (error.code !== 'ENOENT') throw error; }
21
+ }
22
+ return current;
23
+ }
24
+ function list(dir, rel = '') {
25
+ return fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap(e => {
26
+ const name = rel + e.name;
27
+ if (['node_modules', '.next', '.git'].includes(e.name) || e.name.startsWith('.env')) return [];
28
+ if (e.isSymbolicLink()) throw Error(`Symlink in release: ${path.join(dir, e.name)}`);
29
+ return e.isDirectory() ? list(path.join(dir, e.name), name + '/') : [name];
30
+ });
36
31
  }
37
- const hash = (p) =>
38
- fs.existsSync(p)
39
- ? crypto.createHash("sha256").update(fs.readFileSync(p)).digest("hex")
40
- : null;
41
- export function plan(target) {
32
+ export function plan(target, { allowPending = false } = {}) {
42
33
  target = fs.realpathSync(target);
43
- const previous = fs.existsSync(path.join(target, ".design-labs-install.json"))
44
- ? JSON.parse(
45
- fs.readFileSync(path.join(target, ".design-labs-install.json")),
46
- )
47
- : { files: {} };
48
- const changes = [];
49
- const files = {};
34
+ if (!allowPending && fs.existsSync(pendingFile(target))) throw Error(`Interrupted update: inspect ${pendingFile(target)} and roll back before continuing`);
35
+ const manifest = safePath(target, '.design-labs-install.json');
36
+ const previous = fs.existsSync(manifest) ? JSON.parse(fs.readFileSync(manifest)) : { files: {} };
37
+ if (!previous.files || typeof previous.files !== 'object') throw Error('Invalid install manifest');
38
+ const changes = [], files = {};
50
39
  for (const entry of managed) {
51
- const source = path.join(product, "apps/workspace", entry);
40
+ const source = safePath(path.join(product, 'apps/workspace'), entry);
52
41
  if (!fs.existsSync(source)) continue;
53
- for (const f of fs.statSync(source).isDirectory()
54
- ? list(source).map((f) => entry + "/" + f)
55
- : [entry]) {
56
- const next = hash(path.join(product, "apps/workspace", f)),
57
- current = hash(path.join(target, f));
42
+ for (const f of fs.statSync(source).isDirectory() ? list(source).map(f => entry + '/' + f) : [entry]) {
43
+ const next = hash(safePath(path.join(product, 'apps/workspace'), f));
44
+ const current = hash(safePath(target, f));
58
45
  files[f] = next;
59
- if (next !== current)
60
- changes.push({
61
- file: f,
62
- current,
63
- next,
64
- conflict: !!current && previous.files[f] !== current,
65
- });
46
+ if (next !== current) changes.push({ file: f, current, next, conflict: previous.files[f] !== undefined ? previous.files[f] !== current : current !== null });
66
47
  }
67
48
  }
49
+ const configFile = safePath(target, 'lab.config.json');
50
+ const packageFile = safePath(target, 'package.json');
51
+ const config = JSON.parse(fs.readFileSync(configFile));
52
+ const originDrift = (config.versions || []).filter(v => v.origin).map(v => {
53
+ try {
54
+ const origin = fs.realpathSync(v.origin);
55
+ const exclude = target.startsWith(origin + path.sep) ? target : null;
56
+ const currentHash = fingerprint(hashes(origin, exclude));
57
+ return { key: v.key, currentHash, drift: v.originHashes ? currentHash !== fingerprint(v.originHashes) : null };
58
+ } catch (error) { return { key: v.key, drift: null, error: error.message }; }
59
+ });
68
60
  const report = {
69
61
  target,
70
- changes,
71
- files,
72
- configHash: hash(path.join(target, "lab.config.json")),
73
- packageHash: hash(path.join(target, "package.json")),
74
- dependencies: JSON.parse(
75
- fs.readFileSync(path.join(product, "apps/workspace/package.json")),
76
- ),
77
- };
78
- return {
79
- ...report,
80
- token: crypto
81
- .createHash("sha256")
82
- .update(JSON.stringify(report))
83
- .digest("hex"),
62
+ releaseVersion: JSON.parse(fs.readFileSync(path.join(product, 'package.json'))).version,
63
+ changes, files,
64
+ retainedObsoleteFiles: Object.keys(previous.files).filter(f => !Object.hasOwn(files, f)).sort(),
65
+ manifestHash: hash(manifest), configHash: hash(configFile), packageHash: hash(packageFile), originDrift,
66
+ requiredDependencies: JSON.parse(fs.readFileSync(path.join(product, 'apps/workspace/package.json'))),
84
67
  };
68
+ return { ...report, token: crypto.createHash('sha256').update(JSON.stringify(report)).digest('hex') };
85
69
  }
86
70
  export function update(target, token, acceptLocal = false) {
87
71
  const p = plan(target);
88
- if (token !== p.token)
89
- throw Error("Review the update plan and use its current token");
90
- if (p.changes.some((c) => c.conflict) && !acceptLocal)
91
- throw Error(
92
- "Locally modified or untracked platform files; review before --accept-local",
93
- );
94
- const backup = path.join(
95
- path.dirname(target),
96
- ".design-labs-backups",
97
- path.basename(target) + "-" + Date.now(),
98
- );
99
- fs.mkdirSync(path.dirname(backup), { recursive: true });
100
- fs.cpSync(target, backup, {
101
- recursive: true,
102
- filter: (src) =>
103
- !["node_modules", ".next", ".git"].includes(path.basename(src)) &&
104
- !path.basename(src).startsWith(".env"),
105
- });
72
+ target = p.target;
73
+ if (token !== p.token) throw Error('Review the update plan and use its current token');
74
+ if (p.changes.some(c => c.conflict) && !acceptLocal) throw Error('Locally modified or untracked platform files; review before --accept-local');
75
+ if (!p.changes.length) return { changed: false, next: 'No platform changes; dependency settings were not changed.' };
76
+ const directory = backupDir(target);
77
+ fs.mkdirSync(directory, { recursive: true });
78
+ const backup = path.join(directory, path.basename(target) + '-' + crypto.randomUUID());
79
+ const pending = pendingFile(target);
80
+ const fd = fs.openSync(pending, 'wx');
81
+ try { fs.writeFileSync(fd, JSON.stringify({ target, backup, stage: 'backup' }, null, 2)); }
82
+ finally { fs.closeSync(fd); }
106
83
  try {
84
+ fs.cpSync(target, backup, { recursive: true, filter: src => {
85
+ const name = path.basename(src);
86
+ if (['node_modules', '.next', '.git'].includes(name) || name.startsWith('.env')) return false;
87
+ if (fs.lstatSync(src).isSymbolicLink()) throw Error(`Symlink in backup: ${src}`);
88
+ return true;
89
+ } });
90
+ // A review is only valid for the state that was backed up. Recheck all
91
+ // review-bound inputs before the first platform write.
92
+ if (plan(target, { allowPending: true }).token !== p.token) throw Error('Update inputs changed during backup; inspect the marker and review again');
93
+ for (const c of p.changes) {
94
+ if (c.current !== null && hash(safePath(backup, c.file)) !== c.current) throw Error(`Backup changed during copying: ${c.file}`);
95
+ }
96
+ if (hash(safePath(backup, '.design-labs-install.json')) !== p.manifestHash || hash(safePath(backup, 'package.json')) !== p.packageHash || hash(safePath(backup, 'lab.config.json')) !== p.configHash) throw Error('Backup settings changed during copying');
97
+ const nextManifest = JSON.stringify({ version: 2, files: p.files }, null, 2);
98
+ const nextManifestHash = crypto.createHash('sha256').update(nextManifest).digest('hex');
99
+ fs.writeFileSync(backup + '.json', JSON.stringify({ target, changes: p.changes, manifestHash: p.manifestHash, nextManifestHash }, null, 2));
100
+ fs.writeFileSync(pending, JSON.stringify({ target, backup, stage: 'apply' }, null, 2));
107
101
  for (const c of p.changes) {
108
- const dst = path.join(target, c.file);
102
+ const dst = safePath(target, c.file);
103
+ if (hash(dst) !== c.current || hash(safePath(path.join(product, 'apps/workspace'), c.file)) !== c.next) throw Error(`Update file changed after review: ${c.file}`);
109
104
  fs.mkdirSync(path.dirname(dst), { recursive: true });
110
- fs.copyFileSync(path.join(product, "apps/workspace", c.file), dst);
105
+ fs.copyFileSync(safePath(path.join(product, 'apps/workspace'), c.file), dst);
111
106
  }
112
- const local = JSON.parse(
113
- fs.readFileSync(path.join(target, "package.json")),
114
- );
115
- Object.assign(local.dependencies, p.dependencies.dependencies);
116
- Object.assign(local.devDependencies, p.dependencies.devDependencies);
117
- local.scripts.dev = p.dependencies.scripts.dev;
118
- fs.writeFileSync(
119
- path.join(target, "package.json"),
120
- JSON.stringify(local, null, 2) + "\n",
121
- );
122
- const moves = migrate(target);
123
- fs.writeFileSync(
124
- path.join(target, ".design-labs-install.json"),
125
- JSON.stringify({ version: 2, files: p.files }, null, 2),
126
- );
127
- return {
128
- backup,
129
- moves,
130
- next: "Install workspace dependencies, run types/build/browser checks. If these fail, use rollback.",
131
- };
107
+ fs.writeFileSync(path.join(target, '.design-labs-install.json'), nextManifest);
108
+ fs.unlinkSync(pending);
109
+ return { changed: true, backup, retainedObsoleteFiles: p.retainedObsoleteFiles, next: 'Review dependency requirements, run checks and browser tests; use rollback if needed.' };
132
110
  } catch (e) {
133
- throw Error(`${e.message}; recovery backup: ${backup}`);
111
+ throw Error(`${e.message}; update marker: ${pending}; inspect backup before recovery: ${backup}`);
134
112
  }
135
113
  }
136
114
  export function rollback(target, backup) {
137
- if (
138
- path.dirname(backup) !==
139
- path.join(path.dirname(target), ".design-labs-backups") ||
140
- !path.basename(backup).startsWith(path.basename(target) + "-") ||
141
- !fs.existsSync(backup)
142
- )
143
- throw Error("Invalid backup");
144
- const failed = path.join(
145
- path.dirname(target),
146
- ".design-labs-backups",
147
- path.basename(target) + "-failed-" + Date.now(),
148
- );
149
- fs.renameSync(target, failed);
150
- fs.cpSync(backup, target, { recursive: true });
151
- // Environments are intentionally absent from portable backups. Preserve
152
- // local environment files from the failed installation during rollback.
153
- function restoreEnvironment(dir, relative = "") {
154
- for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
155
- if (["node_modules", ".next", ".git"].includes(entry.name)) continue;
156
- const name = path.join(relative, entry.name);
157
- if (entry.isDirectory())
158
- restoreEnvironment(path.join(dir, entry.name), name);
159
- else if (entry.name.startsWith(".env") && !entry.isSymbolicLink()) {
160
- const destination = path.join(target, name);
161
- fs.mkdirSync(path.dirname(destination), { recursive: true });
162
- fs.copyFileSync(path.join(dir, entry.name), destination);
163
- }
164
- }
115
+ target = fs.realpathSync(target); backup = path.resolve(backup);
116
+ if (path.dirname(backup) !== backupDir(target) || !path.basename(backup).startsWith(path.basename(target) + '-') || !fs.existsSync(backup) || !fs.existsSync(backup + '.json')) throw Error('Invalid or incomplete backup');
117
+ const pending = pendingFile(target);
118
+ if (fs.existsSync(pending)) {
119
+ const record = JSON.parse(fs.readFileSync(pending));
120
+ if (record.backup !== backup || record.stage !== 'apply') throw Error('Backup is incomplete or does not match interrupted update; inspect manually');
165
121
  }
166
- restoreEnvironment(failed);
167
- return {
168
- restored: target,
169
- failed,
170
- next: "Reinstall dependencies before launch",
171
- };
172
- }
173
- if (
174
- process.argv[1] &&
175
- path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
176
- ) {
177
- try {
178
- const [cmd, target, token, ...flags] = process.argv.slice(2);
179
- console.log(
180
- JSON.stringify(
181
- cmd === "plan" || cmd === "fix"
182
- ? plan(path.resolve(target))
183
- : cmd === "apply"
184
- ? update(
185
- path.resolve(target),
186
- token,
187
- flags.includes("--accept-local"),
188
- )
189
- : cmd === "rollback"
190
- ? rollback(path.resolve(target), path.resolve(token))
191
- : (() => {
192
- throw Error(
193
- "Use plan|fix <installed-lab>, apply <lab> <token> [--accept-local], rollback <lab> <backup>",
194
- );
195
- })(),
196
- null,
197
- 2,
198
- ),
199
- );
200
- } catch (e) {
201
- console.error(e.message);
202
- process.exitCode = 1;
122
+ const journal = JSON.parse(fs.readFileSync(backup + '.json'));
123
+ if (journal.target !== target || !Array.isArray(journal.changes)) throw Error('Invalid backup journal');
124
+ // Do not overwrite work done since the update; an interrupted apply may have
125
+ // left each file at either its reviewed old or new hash.
126
+ for (const change of journal.changes) {
127
+ if (typeof change.file !== 'string' || !managed.some(e => change.file === e || change.file.startsWith(e + '/')) || change.file.split('/').some(p => p === '..' || p === '.')) throw Error('Invalid backup journal path');
128
+ const current = hash(safePath(target, change.file));
129
+ if (current !== change.current && current !== change.next) throw Error(`Rollback conflict: ${change.file} changed since the update`);
130
+ if (change.current !== null && hash(safePath(backup, change.file)) !== change.current) throw Error(`Backup hash mismatch: ${change.file}`);
131
+ }
132
+ const manifest = safePath(target, '.design-labs-install.json');
133
+ const backedManifest = safePath(backup, '.design-labs-install.json');
134
+ if (hash(backedManifest) !== journal.manifestHash) throw Error('Backup manifest hash mismatch');
135
+ if (![journal.manifestHash, journal.nextManifestHash].includes(hash(manifest))) throw Error('Rollback conflict: install manifest changed since the update');
136
+ for (const change of journal.changes) {
137
+ const dest = safePath(target, change.file);
138
+ if (change.current === null) { if (fs.existsSync(dest)) fs.unlinkSync(dest); }
139
+ else { fs.mkdirSync(path.dirname(dest), { recursive: true }); fs.copyFileSync(safePath(backup, change.file), dest); }
203
140
  }
141
+ if (journal.manifestHash === null) { if (fs.existsSync(manifest)) fs.unlinkSync(manifest); }
142
+ else fs.copyFileSync(backedManifest, manifest);
143
+ if (fs.existsSync(pending)) fs.unlinkSync(pending);
144
+ return { restored: target, backup, next: 'Run checks before launch. Local source, settings and environments were retained.' };
145
+ }
146
+ export function runUpdate(args) {
147
+ const [cmd, target, token, ...flags] = args;
148
+ if (!target || !['plan', 'fix', 'apply', 'rollback'].includes(cmd)) throw Error('Use update plan|fix <installed-lab>, update apply <lab> <token> [--accept-local], or update rollback <lab> <backup>');
149
+ if ((cmd === 'apply' || cmd === 'rollback') && !token) throw Error('Missing review token or backup path');
150
+ return cmd === 'plan' || cmd === 'fix' ? plan(path.resolve(target)) : cmd === 'apply' ? update(path.resolve(target), token, flags.includes('--accept-local')) : rollback(path.resolve(target), path.resolve(token));
151
+ }
152
+ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
153
+ try { console.log(JSON.stringify(runUpdate(process.argv.slice(2)), null, 2)); }
154
+ catch (e) { console.error(e.message); process.exitCode = 1; }
204
155
  }