@ductape/cli 0.5.8 → 0.5.9
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 +25 -0
- package/dist/commands/ui.d.ts +58 -0
- package/dist/commands/ui.js +359 -0
- package/dist/index.js +92 -2
- package/dist/lib/ui/check.d.ts +38 -0
- package/dist/lib/ui/check.js +64 -0
- package/dist/lib/ui/consume.d.ts +92 -0
- package/dist/lib/ui/consume.js +392 -0
- package/dist/lib/ui/manifest.d.ts +53 -0
- package/dist/lib/ui/manifest.js +109 -0
- package/dist/lib/ui/pack.d.ts +39 -0
- package/dist/lib/ui/pack.js +96 -0
- package/dist/lib/ui/paths.d.ts +7 -0
- package/dist/lib/ui/paths.js +25 -0
- package/dist/lib/ui/registry.d.ts +84 -0
- package/dist/lib/ui/registry.js +78 -0
- package/dist/lib/ui/scaffold.d.ts +14 -0
- package/dist/lib/ui/scaffold.js +411 -0
- package/dist/lib/ui/semver.d.ts +11 -0
- package/dist/lib/ui/semver.js +115 -0
- package/dist/lib/ui/validate.d.ts +33 -0
- package/dist/lib/ui/validate.js +445 -0
- package/package.json +3 -2
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The manifest of a Ductape UI piece: ui.json at the root of its directory. A UI piece is frontend source that a workspace
|
|
3
|
+
* publishes once and its applications add to their own repositories, where their own bundler compiles it.
|
|
4
|
+
*/
|
|
5
|
+
export const UI_MANIFEST_FILE = 'ui.json';
|
|
6
|
+
/**
|
|
7
|
+
* Frameworks a UI piece can be written for. A "javascript" piece is plain DOM code (a mount function and a custom element) and
|
|
8
|
+
* can be used by an application of any framework.
|
|
9
|
+
*/
|
|
10
|
+
export const UI_FRAMEWORKS = ['react', 'vue', 'javascript'];
|
|
11
|
+
/** The package each framework needs in the consuming application. Plain JavaScript needs none. */
|
|
12
|
+
export const FRAMEWORK_PEER = { react: 'react', vue: 'vue', javascript: undefined };
|
|
13
|
+
/** Whether a piece of framework `used` can be used by a piece or an application of framework `user`. */
|
|
14
|
+
export const frameworkFits = (user, used) => used === user || used === 'javascript';
|
|
15
|
+
export const NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
|
|
16
|
+
export const EXACT_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
|
|
17
|
+
const TAG = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/;
|
|
18
|
+
const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
|
|
19
|
+
const KNOWN_KEYS = new Set(['name', 'version', 'framework', 'entry', 'description', 'peerDependencies', 'uses', 'requires']);
|
|
20
|
+
const KNOWN_REQUIRES = new Set(['actions', 'features', 'sessions']);
|
|
21
|
+
const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
|
|
22
|
+
const err = (code, message) => ({ severity: 'error', code, message, file: UI_MANIFEST_FILE });
|
|
23
|
+
/** Checks the shape of a manifest. Returns the typed manifest only when there are no errors. */
|
|
24
|
+
export function validateManifest(raw) {
|
|
25
|
+
const diagnostics = [];
|
|
26
|
+
if (!isRecord(raw))
|
|
27
|
+
return { diagnostics: [err('UI_MANIFEST_INVALID', 'ui.json must be a JSON object')] };
|
|
28
|
+
for (const key of Object.keys(raw)) {
|
|
29
|
+
if (!KNOWN_KEYS.has(key))
|
|
30
|
+
diagnostics.push(err('UI_MANIFEST_UNKNOWN_KEY', `Unknown field "${key}" in ui.json`));
|
|
31
|
+
}
|
|
32
|
+
if (typeof raw.name !== 'string' || !NAME_PATTERN.test(raw.name) || raw.name.length > 64) {
|
|
33
|
+
diagnostics.push(err('UI_MANIFEST_NAME', 'name must be lowercase words joined by hyphens, such as "order-table", at most 64 characters'));
|
|
34
|
+
}
|
|
35
|
+
if (typeof raw.version !== 'string' || !EXACT_VERSION.test(raw.version)) {
|
|
36
|
+
diagnostics.push(err('UI_MANIFEST_VERSION', 'version must be an exact semantic version such as "1.0.0"'));
|
|
37
|
+
}
|
|
38
|
+
if (typeof raw.framework !== 'string' || !UI_FRAMEWORKS.includes(raw.framework)) {
|
|
39
|
+
diagnostics.push(err('UI_MANIFEST_FRAMEWORK', `framework must be one of: ${UI_FRAMEWORKS.join(', ')}`));
|
|
40
|
+
}
|
|
41
|
+
if (typeof raw.entry !== 'string' || raw.entry.length === 0) {
|
|
42
|
+
diagnostics.push(err('UI_MANIFEST_ENTRY', 'entry must name the module to import, such as "index.tsx"'));
|
|
43
|
+
}
|
|
44
|
+
if (raw.description !== undefined && typeof raw.description !== 'string') {
|
|
45
|
+
diagnostics.push(err('UI_MANIFEST_DESCRIPTION', 'description must be a string'));
|
|
46
|
+
}
|
|
47
|
+
if (!isRecord(raw.peerDependencies)) {
|
|
48
|
+
diagnostics.push(err('UI_MANIFEST_PEERS', 'peerDependencies must be an object of package name to supported version range'));
|
|
49
|
+
}
|
|
50
|
+
else {
|
|
51
|
+
for (const [pkg, range] of Object.entries(raw.peerDependencies)) {
|
|
52
|
+
if (!PACKAGE_NAME.test(pkg))
|
|
53
|
+
diagnostics.push(err('UI_MANIFEST_PEERS', `"${pkg}" is not a valid npm package name`));
|
|
54
|
+
if (typeof range !== 'string' || range.trim() === '')
|
|
55
|
+
diagnostics.push(err('UI_MANIFEST_PEERS', `peerDependencies["${pkg}"] must be a version range`));
|
|
56
|
+
}
|
|
57
|
+
const framework = raw.framework;
|
|
58
|
+
const needed = FRAMEWORK_PEER[framework];
|
|
59
|
+
if (needed && !(needed in raw.peerDependencies)) {
|
|
60
|
+
diagnostics.push(err('UI_MANIFEST_FRAMEWORK_PEER', `A ${framework} piece must list "${needed}" in peerDependencies`));
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
if (raw.uses !== undefined) {
|
|
64
|
+
if (!isRecord(raw.uses))
|
|
65
|
+
diagnostics.push(err('UI_MANIFEST_USES', 'uses must be an object of UI piece name to exact version'));
|
|
66
|
+
else {
|
|
67
|
+
for (const [name, version] of Object.entries(raw.uses)) {
|
|
68
|
+
if (!NAME_PATTERN.test(name))
|
|
69
|
+
diagnostics.push(err('UI_MANIFEST_USES', `uses: "${name}" is not a valid UI piece name`));
|
|
70
|
+
if (name === raw.name)
|
|
71
|
+
diagnostics.push(err('UI_MANIFEST_USES', 'A UI piece cannot use itself'));
|
|
72
|
+
if (typeof version !== 'string' || !EXACT_VERSION.test(version)) {
|
|
73
|
+
diagnostics.push(err('UI_MANIFEST_USES', `uses["${name}"] must be an exact version such as "1.0.0", not a range`));
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
if (raw.requires !== undefined) {
|
|
79
|
+
if (!isRecord(raw.requires))
|
|
80
|
+
diagnostics.push(err('UI_MANIFEST_REQUIRES', 'requires must be an object'));
|
|
81
|
+
else {
|
|
82
|
+
const requires = raw.requires;
|
|
83
|
+
for (const key of Object.keys(requires)) {
|
|
84
|
+
if (!KNOWN_REQUIRES.has(key))
|
|
85
|
+
diagnostics.push(err('UI_MANIFEST_REQUIRES', `Unknown requirement "${key}": use actions, features or sessions`));
|
|
86
|
+
}
|
|
87
|
+
if (requires.actions !== undefined) {
|
|
88
|
+
if (!Array.isArray(requires.actions))
|
|
89
|
+
diagnostics.push(err('UI_MANIFEST_REQUIRES', 'requires.actions must be a list of { "app", "action" }'));
|
|
90
|
+
else
|
|
91
|
+
requires.actions.forEach((item, index) => {
|
|
92
|
+
if (!isRecord(item) || typeof item.app !== 'string' || !TAG.test(item.app) || typeof item.action !== 'string' || !TAG.test(item.action)
|
|
93
|
+
|| Object.keys(item).some((k) => k !== 'app' && k !== 'action')) {
|
|
94
|
+
diagnostics.push(err('UI_MANIFEST_REQUIRES', `requires.actions[${index}] must be { "app": "<app tag>", "action": "<action tag>" }`));
|
|
95
|
+
}
|
|
96
|
+
});
|
|
97
|
+
}
|
|
98
|
+
for (const key of ['features', 'sessions']) {
|
|
99
|
+
const list = requires[key];
|
|
100
|
+
if (list === undefined)
|
|
101
|
+
continue;
|
|
102
|
+
if (!Array.isArray(list) || list.some((tag) => typeof tag !== 'string' || !TAG.test(tag))) {
|
|
103
|
+
diagnostics.push(err('UI_MANIFEST_REQUIRES', `requires.${key} must be a list of ${key === 'features' ? 'feature' : 'session'} tags`));
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
return diagnostics.length === 0 ? { manifest: raw, diagnostics } : { diagnostics };
|
|
109
|
+
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { type IUiDiagnostic, type IUiManifest } from './manifest.js';
|
|
2
|
+
/**
|
|
3
|
+
* A packed UI piece: its manifest and the full text of each file, with a hash over all of it. JSON rather than a tar
|
|
4
|
+
* archive, so unpacking has no links, modes or archive tricks to defend against: only checked paths and text.
|
|
5
|
+
*/
|
|
6
|
+
export declare const UI_PACK_FORMAT = "ductape-ui/1";
|
|
7
|
+
export interface IUiPackFile {
|
|
8
|
+
path: string;
|
|
9
|
+
sha256: string;
|
|
10
|
+
bytes: number;
|
|
11
|
+
content: string;
|
|
12
|
+
}
|
|
13
|
+
export interface IUiPack {
|
|
14
|
+
format: typeof UI_PACK_FORMAT;
|
|
15
|
+
manifest: IUiManifest;
|
|
16
|
+
files: IUiPackFile[];
|
|
17
|
+
/** sha256 over the canonical form of the format, manifest and every file's path, hash and size. */
|
|
18
|
+
integrity: string;
|
|
19
|
+
}
|
|
20
|
+
export declare const MAX_FILES = 200;
|
|
21
|
+
export declare const MAX_FILE_BYTES: number;
|
|
22
|
+
export declare const MAX_TOTAL_BYTES: number;
|
|
23
|
+
/** JSON with object keys sorted at every level, so equal content always hashes equally. Same rule as Deploy release hashes. */
|
|
24
|
+
export declare function canonicalJson(value: unknown): string;
|
|
25
|
+
export declare const sha256Hex: (data: string | Buffer) => string;
|
|
26
|
+
export declare function computeIntegrity(manifest: IUiManifest, files: Array<Pick<IUiPackFile, 'path' | 'sha256' | 'bytes'>>): string;
|
|
27
|
+
/** Builds a pack from files that have already been read and validated. */
|
|
28
|
+
export declare function buildPack(manifest: IUiManifest, files: Array<{
|
|
29
|
+
path: string;
|
|
30
|
+
content: string;
|
|
31
|
+
}>): IUiPack;
|
|
32
|
+
/**
|
|
33
|
+
* Checks a pack that came from somewhere else (the registry, a cache, a file) before anything in it is used. When
|
|
34
|
+
* `expectedIntegrity` is given, as it is from a lockfile, the pack must be exactly that artifact.
|
|
35
|
+
*/
|
|
36
|
+
export declare function verifyPack(raw: unknown, expectedIntegrity?: string): {
|
|
37
|
+
pack?: IUiPack;
|
|
38
|
+
diagnostics: IUiDiagnostic[];
|
|
39
|
+
};
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
import { isSafeRelativePath } from './paths.js';
|
|
3
|
+
import { validateManifest } from './manifest.js';
|
|
4
|
+
/**
|
|
5
|
+
* A packed UI piece: its manifest and the full text of each file, with a hash over all of it. JSON rather than a tar
|
|
6
|
+
* archive, so unpacking has no links, modes or archive tricks to defend against: only checked paths and text.
|
|
7
|
+
*/
|
|
8
|
+
export const UI_PACK_FORMAT = 'ductape-ui/1';
|
|
9
|
+
export const MAX_FILES = 200;
|
|
10
|
+
export const MAX_FILE_BYTES = 256 * 1024;
|
|
11
|
+
export const MAX_TOTAL_BYTES = 1024 * 1024;
|
|
12
|
+
/** JSON with object keys sorted at every level, so equal content always hashes equally. Same rule as Deploy release hashes. */
|
|
13
|
+
export function canonicalJson(value) {
|
|
14
|
+
if (value === undefined)
|
|
15
|
+
throw new Error('canonicalJson cannot encode undefined');
|
|
16
|
+
if (value === null || typeof value !== 'object')
|
|
17
|
+
return JSON.stringify(value);
|
|
18
|
+
if (Array.isArray(value))
|
|
19
|
+
return `[${value.map(canonicalJson).join(',')}]`;
|
|
20
|
+
const entries = Object.entries(value)
|
|
21
|
+
.filter(([, inner]) => inner !== undefined)
|
|
22
|
+
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
|
|
23
|
+
return `{${entries.map(([key, inner]) => `${JSON.stringify(key)}:${canonicalJson(inner)}`).join(',')}}`;
|
|
24
|
+
}
|
|
25
|
+
export const sha256Hex = (data) => createHash('sha256').update(data).digest('hex');
|
|
26
|
+
export function computeIntegrity(manifest, files) {
|
|
27
|
+
const listing = [...files].map(({ path, sha256, bytes }) => ({ path, sha256, bytes })).sort((a, b) => (a.path < b.path ? -1 : 1));
|
|
28
|
+
return `sha256:${sha256Hex(canonicalJson({ format: UI_PACK_FORMAT, manifest, files: listing }))}`;
|
|
29
|
+
}
|
|
30
|
+
/** Builds a pack from files that have already been read and validated. */
|
|
31
|
+
export function buildPack(manifest, files) {
|
|
32
|
+
const packed = files
|
|
33
|
+
.map(({ path, content }) => ({ path, content, sha256: sha256Hex(content), bytes: Buffer.byteLength(content, 'utf8') }))
|
|
34
|
+
.sort((a, b) => (a.path < b.path ? -1 : 1));
|
|
35
|
+
return { format: UI_PACK_FORMAT, manifest, files: packed, integrity: computeIntegrity(manifest, packed) };
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Checks a pack that came from somewhere else (the registry, a cache, a file) before anything in it is used. When
|
|
39
|
+
* `expectedIntegrity` is given, as it is from a lockfile, the pack must be exactly that artifact.
|
|
40
|
+
*/
|
|
41
|
+
export function verifyPack(raw, expectedIntegrity) {
|
|
42
|
+
const diagnostics = [];
|
|
43
|
+
const fail = (code, message, file) => diagnostics.push({ severity: 'error', code, message, ...(file ? { file } : {}) });
|
|
44
|
+
if (!raw || typeof raw !== 'object' || Array.isArray(raw))
|
|
45
|
+
return { diagnostics: [{ severity: 'error', code: 'UI_PACK_INVALID', message: 'The artifact is not a JSON object' }] };
|
|
46
|
+
const candidate = raw;
|
|
47
|
+
if (candidate.format !== UI_PACK_FORMAT)
|
|
48
|
+
fail('UI_PACK_FORMAT', `Unsupported artifact format "${String(candidate.format)}"; expected ${UI_PACK_FORMAT}`);
|
|
49
|
+
const { manifest, diagnostics: manifestDiagnostics } = validateManifest(candidate.manifest);
|
|
50
|
+
diagnostics.push(...manifestDiagnostics);
|
|
51
|
+
if (!Array.isArray(candidate.files)) {
|
|
52
|
+
fail('UI_PACK_FILES', 'The artifact has no file list');
|
|
53
|
+
return { diagnostics };
|
|
54
|
+
}
|
|
55
|
+
if (candidate.files.length > MAX_FILES)
|
|
56
|
+
fail('UI_PACK_LIMIT', `The artifact has ${candidate.files.length} files; at most ${MAX_FILES} are allowed`);
|
|
57
|
+
const seen = new Set();
|
|
58
|
+
let total = 0;
|
|
59
|
+
for (const file of candidate.files) {
|
|
60
|
+
const where = typeof file?.path === 'string' ? file.path : undefined;
|
|
61
|
+
if (!file || typeof file.path !== 'string' || !isSafeRelativePath(file.path)) {
|
|
62
|
+
fail('UI_PACK_PATH', `Unsafe or missing file path ${JSON.stringify(file?.path)}`);
|
|
63
|
+
continue;
|
|
64
|
+
}
|
|
65
|
+
const folded = file.path.toLowerCase();
|
|
66
|
+
if (seen.has(folded))
|
|
67
|
+
fail('UI_PACK_DUPLICATE', 'Two files share this path (ignoring letter case)', where);
|
|
68
|
+
seen.add(folded);
|
|
69
|
+
if (typeof file.content !== 'string') {
|
|
70
|
+
fail('UI_PACK_CONTENT', 'File content must be text', where);
|
|
71
|
+
continue;
|
|
72
|
+
}
|
|
73
|
+
const bytes = Buffer.byteLength(file.content, 'utf8');
|
|
74
|
+
total += bytes;
|
|
75
|
+
if (bytes > MAX_FILE_BYTES)
|
|
76
|
+
fail('UI_PACK_LIMIT', `File is ${bytes} bytes; at most ${MAX_FILE_BYTES} are allowed`, where);
|
|
77
|
+
if (file.bytes !== bytes)
|
|
78
|
+
fail('UI_PACK_SIZE', 'Recorded size does not match the content', where);
|
|
79
|
+
if (file.sha256 !== sha256Hex(file.content))
|
|
80
|
+
fail('UI_PACK_HASH', 'Recorded hash does not match the content', where);
|
|
81
|
+
}
|
|
82
|
+
if (total > MAX_TOTAL_BYTES)
|
|
83
|
+
fail('UI_PACK_LIMIT', `The artifact holds ${total} bytes; at most ${MAX_TOTAL_BYTES} are allowed`);
|
|
84
|
+
if (manifest && !candidate.files.some((file) => file?.path === manifest.entry)) {
|
|
85
|
+
fail('UI_PACK_ENTRY', `The entry "${manifest.entry}" is not among the files`);
|
|
86
|
+
}
|
|
87
|
+
if (diagnostics.length === 0 && manifest) {
|
|
88
|
+
const recomputed = computeIntegrity(manifest, candidate.files);
|
|
89
|
+
if (candidate.integrity !== recomputed)
|
|
90
|
+
fail('UI_PACK_INTEGRITY', `Integrity ${String(candidate.integrity)} does not match the content (${recomputed})`);
|
|
91
|
+
else if (expectedIntegrity !== undefined && expectedIntegrity !== recomputed) {
|
|
92
|
+
fail('UI_PACK_INTEGRITY', `Expected ${expectedIntegrity} but the artifact is ${recomputed}`);
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
return diagnostics.length === 0 ? { pack: candidate, diagnostics } : { diagnostics };
|
|
96
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether a path from a UI artifact may be written under the piece's directory. Artifacts are untrusted, so anything
|
|
3
|
+
* that could leave the directory, name a hidden file or mean different files on different systems is refused.
|
|
4
|
+
*/
|
|
5
|
+
export declare function isSafeRelativePath(candidate: string): boolean;
|
|
6
|
+
/** Joins a checked relative path to a root and confirms the result stays inside it. */
|
|
7
|
+
export declare function resolveInside(root: string, relative: string): string;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import path from 'node:path';
|
|
2
|
+
/**
|
|
3
|
+
* Whether a path from a UI artifact may be written under the piece's directory. Artifacts are untrusted, so anything
|
|
4
|
+
* that could leave the directory, name a hidden file or mean different files on different systems is refused.
|
|
5
|
+
*/
|
|
6
|
+
export function isSafeRelativePath(candidate) {
|
|
7
|
+
if (typeof candidate !== 'string' || candidate.length === 0 || candidate.length > 200)
|
|
8
|
+
return false;
|
|
9
|
+
if (candidate.includes('\\') || candidate.includes('\0') || candidate.includes(':'))
|
|
10
|
+
return false;
|
|
11
|
+
if (candidate.startsWith('/'))
|
|
12
|
+
return false;
|
|
13
|
+
const segments = candidate.split('/');
|
|
14
|
+
return segments.every((segment) => segment.length > 0 && segment !== '.' && segment !== '..' && !segment.startsWith('.'));
|
|
15
|
+
}
|
|
16
|
+
/** Joins a checked relative path to a root and confirms the result stays inside it. */
|
|
17
|
+
export function resolveInside(root, relative) {
|
|
18
|
+
if (!isSafeRelativePath(relative))
|
|
19
|
+
throw new Error(`Refusing unsafe path "${relative}"`);
|
|
20
|
+
const resolvedRoot = path.resolve(root);
|
|
21
|
+
const target = path.resolve(resolvedRoot, ...relative.split('/'));
|
|
22
|
+
if (target !== resolvedRoot && !target.startsWith(resolvedRoot + path.sep))
|
|
23
|
+
throw new Error(`Refusing path "${relative}" outside ${root}`);
|
|
24
|
+
return target;
|
|
25
|
+
}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { ApiClient } from '../api-client.js';
|
|
2
|
+
import { type WorkspaceContext } from '../workspace-context.js';
|
|
3
|
+
import { type IUiDiagnostic } from './manifest.js';
|
|
4
|
+
import { type IUiPack } from './pack.js';
|
|
5
|
+
/** The workspace's UI registry on the integrations service. Every call is scoped to the active workspace. */
|
|
6
|
+
export declare const UI_REGISTRY_PATH = "/integrations/v1/ui";
|
|
7
|
+
export interface IUiDeprecation {
|
|
8
|
+
reason?: string;
|
|
9
|
+
replacement?: string;
|
|
10
|
+
at: string;
|
|
11
|
+
by: string;
|
|
12
|
+
}
|
|
13
|
+
export interface IUiVersionSummary {
|
|
14
|
+
name: string;
|
|
15
|
+
version: string;
|
|
16
|
+
framework: string;
|
|
17
|
+
description?: string;
|
|
18
|
+
integrity: string;
|
|
19
|
+
bytes: number;
|
|
20
|
+
files: number;
|
|
21
|
+
publishedAt: string;
|
|
22
|
+
publishedBy: string;
|
|
23
|
+
deprecated: boolean;
|
|
24
|
+
deprecation?: IUiDeprecation;
|
|
25
|
+
}
|
|
26
|
+
export interface IUiPublishResult {
|
|
27
|
+
created: boolean;
|
|
28
|
+
version: IUiVersionSummary;
|
|
29
|
+
warnings: string[];
|
|
30
|
+
}
|
|
31
|
+
export interface IUiListEntry {
|
|
32
|
+
name: string;
|
|
33
|
+
framework: string;
|
|
34
|
+
description?: string;
|
|
35
|
+
latest?: string;
|
|
36
|
+
versions: number;
|
|
37
|
+
updatedAt: string;
|
|
38
|
+
}
|
|
39
|
+
export interface IUiDetail {
|
|
40
|
+
name: string;
|
|
41
|
+
framework: string;
|
|
42
|
+
latest?: string;
|
|
43
|
+
versions: IUiVersionSummary[];
|
|
44
|
+
}
|
|
45
|
+
export interface IUiVersionDetail extends IUiVersionSummary {
|
|
46
|
+
manifest: Record<string, unknown>;
|
|
47
|
+
fileList: Array<{
|
|
48
|
+
path: string;
|
|
49
|
+
sha256: string;
|
|
50
|
+
bytes: number;
|
|
51
|
+
}>;
|
|
52
|
+
}
|
|
53
|
+
/** "order-table" or "order-table@1.2.0" / "order-table@latest". A version is required where `requireVersion` says so. */
|
|
54
|
+
export declare function parseRef(ref: string, requireVersion?: boolean): {
|
|
55
|
+
name: string;
|
|
56
|
+
version?: string;
|
|
57
|
+
};
|
|
58
|
+
export declare class UiRegistry {
|
|
59
|
+
private readonly ctx;
|
|
60
|
+
private readonly api;
|
|
61
|
+
constructor(ctx: WorkspaceContext, api?: ApiClient);
|
|
62
|
+
/** Runs launched for an agent (the MCP server sets DUCTAPE_ACTOR) say so, and the registry records them as an agent's. */
|
|
63
|
+
private request;
|
|
64
|
+
private url;
|
|
65
|
+
private body;
|
|
66
|
+
publish(pack: IUiPack): Promise<IUiPublishResult>;
|
|
67
|
+
list(search?: string): Promise<IUiListEntry[]>;
|
|
68
|
+
get(name: string): Promise<IUiDetail>;
|
|
69
|
+
getVersion(name: string, version: string): Promise<IUiVersionDetail>;
|
|
70
|
+
/**
|
|
71
|
+
* Downloads an artifact and checks it before returning it, so nothing unverified ever reaches a project. With
|
|
72
|
+
* `expectedIntegrity` (from a lockfile) it must be exactly that artifact.
|
|
73
|
+
*/
|
|
74
|
+
fetchPack(name: string, version: string, expectedIntegrity?: string): Promise<{
|
|
75
|
+
pack: IUiPack;
|
|
76
|
+
deprecation?: IUiDeprecation;
|
|
77
|
+
}>;
|
|
78
|
+
deprecate(name: string, version: string, reason: string, replacement?: string): Promise<IUiVersionSummary>;
|
|
79
|
+
undeprecate(name: string, version: string): Promise<IUiVersionSummary>;
|
|
80
|
+
}
|
|
81
|
+
export declare class UiArtifactError extends Error {
|
|
82
|
+
readonly diagnostics: IUiDiagnostic[];
|
|
83
|
+
constructor(message: string, diagnostics: IUiDiagnostic[]);
|
|
84
|
+
}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import { ApiClient } from '../api-client.js';
|
|
2
|
+
import { workspaceAuthQuery } from '../workspace-context.js';
|
|
3
|
+
import { EXACT_VERSION, NAME_PATTERN } from './manifest.js';
|
|
4
|
+
import { verifyPack } from './pack.js';
|
|
5
|
+
/** The workspace's UI registry on the integrations service. Every call is scoped to the active workspace. */
|
|
6
|
+
export const UI_REGISTRY_PATH = '/integrations/v1/ui';
|
|
7
|
+
/** "order-table" or "order-table@1.2.0" / "order-table@latest". A version is required where `requireVersion` says so. */
|
|
8
|
+
export function parseRef(ref, requireVersion = false) {
|
|
9
|
+
const at = ref.lastIndexOf('@');
|
|
10
|
+
const name = at > 0 ? ref.slice(0, at) : ref;
|
|
11
|
+
const version = at > 0 ? ref.slice(at + 1) : undefined;
|
|
12
|
+
if (!NAME_PATTERN.test(name))
|
|
13
|
+
throw new Error(`"${name}" is not a UI piece name (lowercase words joined by hyphens)`);
|
|
14
|
+
if (version !== undefined && version !== 'latest' && !EXACT_VERSION.test(version)) {
|
|
15
|
+
throw new Error(`"${version}" is not an exact version or "latest"; ranges are not used for UI pieces`);
|
|
16
|
+
}
|
|
17
|
+
if (requireVersion && (version === undefined || version === 'latest'))
|
|
18
|
+
throw new Error(`Name the exact version, as in ${name}@1.0.0`);
|
|
19
|
+
return { name, ...(version ? { version } : {}) };
|
|
20
|
+
}
|
|
21
|
+
export class UiRegistry {
|
|
22
|
+
ctx;
|
|
23
|
+
api;
|
|
24
|
+
constructor(ctx, api) {
|
|
25
|
+
this.ctx = ctx;
|
|
26
|
+
this.api = api ?? ApiClient.forProfile(ctx.profile, ctx.credentials);
|
|
27
|
+
}
|
|
28
|
+
/** Runs launched for an agent (the MCP server sets DUCTAPE_ACTOR) say so, and the registry records them as an agent's. */
|
|
29
|
+
request(method, path, body) {
|
|
30
|
+
return this.api.request(method, path, body, process.env.DUCTAPE_ACTOR === 'agent' ? { 'x-ductape-actor': 'agent' } : undefined);
|
|
31
|
+
}
|
|
32
|
+
url(path, extra) {
|
|
33
|
+
return `${UI_REGISTRY_PATH}${path}?${new URLSearchParams(workspaceAuthQuery(this.ctx, extra)).toString()}`;
|
|
34
|
+
}
|
|
35
|
+
body(extra) {
|
|
36
|
+
return { ...workspaceAuthQuery(this.ctx), ...extra };
|
|
37
|
+
}
|
|
38
|
+
publish(pack) {
|
|
39
|
+
return this.request('POST', this.url(''), this.body({ pack, integrity: pack.integrity }));
|
|
40
|
+
}
|
|
41
|
+
list(search) {
|
|
42
|
+
return this.request('GET', this.url('', search ? { search } : undefined));
|
|
43
|
+
}
|
|
44
|
+
get(name) {
|
|
45
|
+
return this.request('GET', this.url(`/${encodeURIComponent(name)}`));
|
|
46
|
+
}
|
|
47
|
+
getVersion(name, version) {
|
|
48
|
+
return this.request('GET', this.url(`/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}`));
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Downloads an artifact and checks it before returning it, so nothing unverified ever reaches a project. With
|
|
52
|
+
* `expectedIntegrity` (from a lockfile) it must be exactly that artifact.
|
|
53
|
+
*/
|
|
54
|
+
async fetchPack(name, version, expectedIntegrity) {
|
|
55
|
+
const result = await this.request('GET', this.url(`/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}/pack`));
|
|
56
|
+
const { pack, diagnostics } = verifyPack(result?.pack, expectedIntegrity);
|
|
57
|
+
if (!pack)
|
|
58
|
+
throw new UiArtifactError(`The registry's artifact for ${name}@${version} failed verification`, diagnostics);
|
|
59
|
+
if (pack.manifest.name !== name || (version !== 'latest' && pack.manifest.version !== version)) {
|
|
60
|
+
throw new UiArtifactError(`Asked for ${name}@${version} but the registry sent ${pack.manifest.name}@${pack.manifest.version}`, []);
|
|
61
|
+
}
|
|
62
|
+
return { pack, ...(result.deprecation ? { deprecation: result.deprecation } : {}) };
|
|
63
|
+
}
|
|
64
|
+
deprecate(name, version, reason, replacement) {
|
|
65
|
+
return this.request('POST', this.url(`/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}/deprecate`), this.body({ reason, ...(replacement ? { replacement } : {}) }));
|
|
66
|
+
}
|
|
67
|
+
undeprecate(name, version) {
|
|
68
|
+
return this.request('POST', this.url(`/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}/undeprecate`), this.body({}));
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
export class UiArtifactError extends Error {
|
|
72
|
+
diagnostics;
|
|
73
|
+
constructor(message, diagnostics) {
|
|
74
|
+
super(diagnostics.length > 0 ? `${message}: ${diagnostics.slice(0, 5).map((d) => `${d.code}${d.file ? ` ${d.file}` : ''} ${d.message}`).join('; ')}` : message);
|
|
75
|
+
this.diagnostics = diagnostics;
|
|
76
|
+
this.name = 'UiArtifactError';
|
|
77
|
+
}
|
|
78
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { type UiFramework } from './manifest.js';
|
|
2
|
+
/** Where a project keeps the UI pieces it writes, and the folder inside it that holds pieces it added from the registry. */
|
|
3
|
+
export declare const UI_DIR: string;
|
|
4
|
+
export declare const INSTALLED_DIR = "installed";
|
|
5
|
+
export declare const pascalCase: (name: string) => string;
|
|
6
|
+
/** The project a command works in: the linked Ductape project, else the nearest folder with a package.json, else here. */
|
|
7
|
+
export declare function uiProjectRoot(linkedDir: string | undefined, start?: string): string;
|
|
8
|
+
/** Writes a new UI piece. Refuses to touch a folder that already exists. */
|
|
9
|
+
export declare function scaffoldUi(projectRoot: string, name: string, framework: UiFramework, description?: string): {
|
|
10
|
+
dir: string;
|
|
11
|
+
files: string[];
|
|
12
|
+
};
|
|
13
|
+
/** The UI pieces a project has written: every folder under ductape/ui with a ui.json, except the installed ones. */
|
|
14
|
+
export declare function listAuthoredUi(projectRoot: string): string[];
|