@angelmsger/fx 0.0.0-stage → 0.10.1

package/dist/adapters/family/cli.js

@@ -0,0 +1,159 @@
+// The one place that knows a family CLI's global flags, JSON envelopes and exit codes
+// (bitbucket-cli, jenkins-cli). Raw stdout is kept too, because some answers are not JSON
+// at all — a file's bytes.
+import { DevkitError } from '../../domain/errors.js';
+import { errorEnvelope, stderrReason } from '../../domain/toolchain/stderr.js';
+import { serviceFlags } from './service.js';
+export const EXIT = {
+    auth: 4,
+    permission: 5,
+    not_found: 6,
+    rate_limit: 7,
+    network: 8,
+    server: 9,
+    conflict: 11,
+    missing_binary: 127,
+};
+export class FamilyCli {
+    binary;
+    process;
+    context;
+    service;
+    constructor(binary, process, context, service) {
+        this.binary = binary;
+        this.process = process;
+        this.context = context;
+        this.service = service;
+    }
+    async call(args, options = {}) {
+        await this.checkService();
+        const global = [
+            '--format',
+            'json',
+            ...(this.context === undefined ? [] : ['--use-context', this.context]),
+            ...(this.service ? serviceFlags(this.service) : []),
+        ];
+        const result = await this.process.run([this.binary, ...global, ...args], {
+            timeoutMs: options.timeoutMs,
+            diagnostic: { phase: `${this.binary} ${args.slice(0, 2).join(' ')}`.trim() },
+        });
+        if (result.code === EXIT.missing_binary)
+            throw toolMissing(this.binary);
+        return {
+            code: result.code,
+            stdout: result.stdout,
+            data: parse(result.stdout),
+            error: envelope(result),
+        };
+    }
+    // Repository synchronization can query the code host without a readiness command.
+    // An unprepared/conflicting preset must never fall through to an authenticated request.
+    async checkService() {
+        if (!this.context || !this.service?.['base_url'])
+            return;
+        const result = await this.process.run([
+            this.binary,
+            'config',
+            'set-context',
+            this.context,
+            ...serviceFlags(this.service),
+            '--dry-run',
+            '--format',
+            'json',
+        ], { timeoutMs: 5000 });
+        if (result.code === 0 && objectOf(parse(result.stdout))?.['changed'] === false)
+            return;
+        throw new DevkitError('config', 'LOGIN_REQUIRED', `${this.binary} service settings are not prepared for this context`, {
+            hint: 'Resolve the public service configuration before making authenticated requests.',
+            handoff: {
+                summary: `${this.binary} requires matching public service settings`,
+                command: 'fx sync --only services',
+                userSteps: [
+                    {
+                        id: `${this.binary}.service`,
+                        kind: 'run',
+                        title: 'Review and prepare public service settings',
+                        command: ['fx', 'sync', '--only', 'services'],
+                    },
+                ],
+            },
+            nextSteps: [
+                'fx sync --only services --dry-run',
+                'fx sync --only services',
+                `fx login ${this.binary}`,
+            ],
+        });
+    }
+}
+export function toolMissing(binary) {
+    return new DevkitError('config', 'TOOL_MISSING', `${binary} is not installed or not on PATH`, {
+        hint: 'The platform is driven through its own CLI.',
+        nextSteps: [`fx can ${binary}`, `fx tool install ${binary}`],
+    });
+}
+// A failed query, classified by the family exit code: credentials, access,
+// or the platform itself; never a guess at what the answer would have been.
+export function queryFailed(binary, call, what) {
+    const detail = call.error?.message ?? `exit ${call.code}`;
+    if (call.code === EXIT.auth) {
+        return new DevkitError('auth', 'PLATFORM_AUTH', `${binary} could not ${what}: ${detail}`, {
+            nextSteps: [`fx login ${binary}`, `${binary} auth status`],
+        });
+    }
+    if (call.code === EXIT.permission) {
+        return new DevkitError('permission', 'PLATFORM_FORBIDDEN', `${binary} may not ${what}: ${detail}`, { nextSteps: [`fx can ${binary}`] });
+    }
+    return new DevkitError(categoryOf(call.code), 'PLATFORM_QUERY_FAILED', `${binary} could not ${what}: ${detail}`, { nextSteps: [`fx doctor --tool ${binary}`] });
+}
+// A zero exit whose payload cannot be read is a failure too: a changed schema
+// must not read as nothing to report. See Coverage in domain/report.ts.
+export function unreadableError(binary, what) {
+    return new DevkitError('server', 'PLATFORM_QUERY_FAILED', `${binary} answered with ${what} it could not read`, { nextSteps: [`fx doctor --tool ${binary}`] });
+}
+export function objectOf(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+// A family list answer is `{items, has_more, next?}`; a bare array is accepted
+// for tools that answer without the envelope. undefined means the answer is not
+// a list of records, does not say whether it is complete, or is short of its own
+// last page.
+export function itemsOf(value) {
+    const envelope = objectOf(value);
+    const list = Array.isArray(value) ? value : envelope?.['items'];
+    if (!Array.isArray(list))
+        return undefined;
+    if (envelope !== undefined && typeof envelope['has_more'] !== 'boolean')
+        return undefined;
+    if (envelope?.['has_more'] === true)
+        return undefined;
+    const rows = list.map(objectOf);
+    return rows.every((row) => row !== undefined) ? rows : undefined;
+}
+export function stringAt(record, key) {
+    const value = record[key];
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+function categoryOf(code) {
+    if (code === EXIT.rate_limit)
+        return 'rate_limit';
+    if (code === EXIT.network)
+        return 'network';
+    return 'server';
+}
+function parse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function envelope(result) {
+    if (result.code === 0)
+        return undefined;
+    const error = errorEnvelope(result.stderr);
+    return error === undefined ? { message: stderrReason(result.stderr, result.code) } : error;
+}
+//# sourceMappingURL=cli.js.map

package/dist/adapters/family/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../src/adapters/family/cli.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,0FAA0F;AAC1F,2BAA2B;AAE3B,OAAO,EAAiB,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAG/E,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAe5C,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,IAAI,EAAE,CAAC;IACP,UAAU,EAAE,CAAC;IACb,SAAS,EAAE,CAAC;IACZ,UAAU,EAAE,CAAC;IACb,OAAO,EAAE,CAAC;IACV,MAAM,EAAE,CAAC;IACT,QAAQ,EAAE,EAAE;IACZ,cAAc,EAAE,GAAG;CACX,CAAC;AAEX,MAAM,OAAO,SAAS;IAED;IACA;IACA;IACA;IAJnB,YACmB,MAAc,EACd,OAAgB,EAChB,OAA2B,EAC3B,OAA0C;QAH1C,WAAM,GAAN,MAAM,CAAQ;QACd,YAAO,GAAP,OAAO,CAAS;QAChB,YAAO,GAAP,OAAO,CAAoB;QAC3B,YAAO,GAAP,OAAO,CAAmC;IAC1D,CAAC;IAEJ,KAAK,CAAC,IAAI,CAAC,IAAuB,EAAE,UAAuB,EAAE;QAC3D,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG;YACb,UAAU;YACV,MAAM;YACN,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YACtE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACpD,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE;YACvE,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,UAAU,EAAE,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE;SAC7E,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,cAAc;YAAE,MAAM,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxE,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;YAC1B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC;SACxB,CAAC;IACJ,CAAC;IAED,kFAAkF;IAClF,wFAAwF;IAChF,KAAK,CAAC,YAAY;QACxB,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,UAAU,CAAC;YAAE,OAAO;QACzD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CACnC;YACE,IAAI,CAAC,MAAM;YACX,QAAQ;YACR,aAAa;YACb,IAAI,CAAC,OAAO;YACZ,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC;YAC7B,WAAW;YACX,UAAU;YACV,MAAM;SACP,EACD,EAAE,SAAS,EAAE,IAAI,EAAE,CACpB,CAAC;QACF,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,KAAK,KAAK;YAAE,OAAO;QACvF,MAAM,IAAI,WAAW,CACnB,QAAQ,EACR,gBAAgB,EAChB,GAAG,IAAI,CAAC,MAAM,qDAAqD,EACnE;YACE,IAAI,EAAE,gFAAgF;YACtF,OAAO,EAAE;gBACP,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,4CAA4C;gBACnE,OAAO,EAAE,yBAAyB;gBAClC,SAAS,EAAE;oBACT;wBACE,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,UAAU;wBAC5B,IAAI,EAAE,KAAK;wBACX,KAAK,EAAE,4CAA4C;wBACnD,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC;qBAC9C;iBACF;aACF;YACD,SAAS,EAAE;gBACT,mCAAmC;gBACnC,yBAAyB;gBACzB,YAAY,IAAI,CAAC,MAAM,EAAE;aAC1B;SACF,CACF,CAAC;IACJ,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,IAAI,WAAW,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,MAAM,kCAAkC,EAAE;QAC5F,IAAI,EAAE,6CAA6C;QACnD,SAAS,EAAE,CAAC,UAAU,MAAM,EAAE,EAAE,mBAAmB,MAAM,EAAE,CAAC;KAC7D,CAAC,CAAC;AACL,CAAC;AAED,2EAA2E;AAC3E,4EAA4E;AAC5E,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,IAAa,EAAE,IAAY;IACrE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,OAAO,IAAI,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1D,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,OAAO,IAAI,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,cAAc,IAAI,KAAK,MAAM,EAAE,EAAE;YACxF,SAAS,EAAE,CAAC,YAAY,MAAM,EAAE,EAAE,GAAG,MAAM,cAAc,CAAC;SAC3D,CAAC,CAAC;IACL,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;QAClC,OAAO,IAAI,WAAW,CACpB,YAAY,EACZ,oBAAoB,EACpB,GAAG,MAAM,YAAY,IAAI,KAAK,MAAM,EAAE,EACtC,EAAE,SAAS,EAAE,CAAC,UAAU,MAAM,EAAE,CAAC,EAAE,CACpC,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,WAAW,CACpB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EACrB,uBAAuB,EACvB,GAAG,MAAM,cAAc,IAAI,KAAK,MAAM,EAAE,EACxC,EAAE,SAAS,EAAE,CAAC,oBAAoB,MAAM,EAAE,CAAC,EAAE,CAC9C,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,wEAAwE;AACxE,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,IAAY;IAC1D,OAAO,IAAI,WAAW,CACpB,QAAQ,EACR,uBAAuB,EACvB,GAAG,MAAM,kBAAkB,IAAI,oBAAoB,EACnD,EAAE,SAAS,EAAE,CAAC,oBAAoB,MAAM,EAAE,CAAC,EAAE,CAC9C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzE,CAAC,CAAE,KAAiC;QACpC,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,+EAA+E;AAC/E,gFAAgF;AAChF,iFAAiF;AACjF,aAAa;AACb,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC;IAChE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,QAAQ,CAAC,UAAU,CAAC,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1F,IAAI,QAAQ,EAAE,CAAC,UAAU,CAAC,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACtD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAChC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,CAAE,IAAkC,CAAC,CAAC,CAAC,SAAS,CAAC;AAClG,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,MAA+B,EAAE,GAAW;IACnE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvE,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,IAAI,IAAI,KAAK,IAAI,CAAC,UAAU;QAAE,OAAO,YAAY,CAAC;IAClD,IAAI,IAAI,KAAK,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC5C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,KAAK,CAAC,IAAY;IACzB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,MAAqB;IACrC,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AAC7F,CAAC"}

package/dist/adapters/family/service-protocol.js

@@ -0,0 +1,73 @@
+// Decode native context previews and conflicts, exposing only allowlisted public changes.
+import { errorEnvelope } from '../../domain/toolchain/stderr.js';
+import { objectOf } from './cli.js';
+export class FamilyServiceProtocol {
+    plan(stdout) {
+        let data;
+        try {
+            data = objectOf(JSON.parse(stdout));
+        }
+        catch {
+            return { kind: 'unreadable' };
+        }
+        if (data?.['changed'] === false)
+            return { kind: 'unchanged' };
+        if (data?.['changed'] !== true)
+            return { kind: 'unreadable' };
+        const changes = objectOf(data['changes']);
+        return {
+            kind: 'changes',
+            createsContext: changes !== undefined && 'auth.scheme' in changes,
+            changes: publicChanges(changes),
+        };
+    }
+    failure(stderr) {
+        const fields = errorEnvelope(stderr) ?? {};
+        const code = typeof fields['code'] === 'string' ? fields['code'] : null;
+        return {
+            kind: failureKind(code),
+            code,
+            changes: publicChanges(fields['details']),
+        };
+    }
+}
+function failureKind(code) {
+    if (code === 'CONFIG_CONTEXT_CONFLICT')
+        return 'conflict';
+    if (code === 'BROWSER_MANAGED_SESSION')
+        return 'managed_session';
+    return 'unknown';
+}
+function publicChanges(value) {
+    const allowed = new Set([
+        'server',
+        'base_url',
+        'flavor',
+        'org',
+        'auth.scheme',
+        'auth.credential_url',
+        'current_context',
+    ]);
+    return Object.fromEntries(Object.entries(objectOf(value) ?? {}).flatMap(([key, change]) => {
+        if (!allowed.has(key))
+            return [];
+        const row = objectOf(change);
+        if (typeof row?.['before'] !== 'string' || typeof row['after'] !== 'string')
+            return [];
+        return [[key, { before: publicValue(row['before']), after: publicValue(row['after']) }]];
+    }));
+}
+function publicValue(value) {
+    if (!value.includes('://'))
+        return value;
+    try {
+        const url = new URL(value);
+        if (url.username || url.password || url.search || url.hash)
+            return '[redacted non-public URL]';
+        return value;
+    }
+    catch {
+        return '[invalid public URL]';
+    }
+}
+//# sourceMappingURL=service-protocol.js.map

package/dist/adapters/family/service-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-protocol.js","sourceRoot":"","sources":["../../../src/adapters/family/service-protocol.ts"],"names":[],"mappings":"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"}

package/dist/adapters/family/service.js

@@ -0,0 +1,75 @@
+export function familyService(tool, settings, minVersion, statusField = 'configured') {
+    const context = settings.context?.toLowerCase() ?? '';
+    const scope = serviceScope(settings);
+    const browser = settings.auth_scheme === 'session' ? ['--browser'] : [];
+    const preset = (flags) => [
+        'config',
+        'set-context',
+        context,
+        ...flags,
+        '--format',
+        'json',
+    ];
+    return {
+        preparation: {
+            kind: 'command',
+            resource: context,
+            minVersion,
+            command: preset([...serviceFlags(settings), ...signInFlags(settings)]),
+            agrees: preset(serviceFlags(settings)),
+        },
+        recipes: [
+            reuseRecipe(tool, scope),
+            {
+                id: 'credential',
+                tool,
+                perEnv: false,
+                kind: 'run',
+                phase: 'authenticate',
+                requires: ['reuse'],
+                title: `Authenticate ${tool} with your own credentials`,
+                instructions: `Each member obtains their own credentials. Run ${tool} ${scope.join(' ')} auth guide for acquisition instructions. No personal credential is distributed by the manifest.`,
+                ...(settings.credential_url ? { open: settings.credential_url } : {}),
+                run: [...scope, 'auth', 'login', ...browser],
+                verify: {
+                    command: [...scope, 'auth', 'status', '--format', 'json'],
+                    json: { path: statusField, equals: true, reason: 'error' },
+                },
+            },
+        ],
+    };
+}
+// What pins one companion invocation to the declared service instead of the active context.
+export function serviceScope(settings) {
+    return ['--use-context', settings.context?.toLowerCase() ?? '', ...serviceFlags(settings)];
+}
+// Where the service is. Setup, login and live query guards hold a context to this and to
+// nothing else: a person who can reach the declared service is ready however they signed in.
+export function serviceFlags(settings) {
+    return flagsOf(settings, ['base_url', 'flavor', 'org']);
+}
+// How a declaration proposes to sign in. It shapes a context fx creates and the sign-in
+// fx offers; a context that already serves the declared service keeps its own.
+export function signInFlags(settings) {
+    return flagsOf(settings, ['auth_scheme', 'credential_url']);
+}
+function flagsOf(settings, keys) {
+    return keys.flatMap((key) => settings[key] === undefined ? [] : [`--${key.replaceAll('_', '-')}`, settings[key]]);
+}
+function reuseRecipe(tool, scope) {
+    return {
+        id: 'reuse',
+        tool,
+        perEnv: false,
+        kind: 'run',
+        phase: 'prepare',
+        title: `Reuse an existing ${tool} login`,
+        instructions: 'The companion matches and verifies existing credentials before associating their identity with the team context. No personal sign-in or secret export occurs.',
+        run: [...scope, 'auth', 'reuse', '--format', 'json'],
+        verify: {
+            command: [...scope, 'auth', 'reuse', '--dry-run', '--format', 'json'],
+            json: { path: 'changed', equals: false, unmet: 'an existing login can be reused' },
+        },
+    };
+}
+//# sourceMappingURL=service.js.map

package/dist/adapters/family/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../src/adapters/family/service.ts"],"names":[],"mappings":"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"}

package/dist/adapters/fs/directory-replacement.js

@@ -0,0 +1,80 @@
+// Directory replacement records its private staging paths before moving the
+// live directory. Recovery keeps the installed tree, or restores the previous
+// tree when interruption happened between the two renames.
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { DevkitError } from '../../domain/errors.js';
+export async function replaceDirectory(source, target) {
+    const journal = `${target}.fx-transaction`;
+    await recover(target, journal);
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    const token = randomUUID();
+    const tx = {
+        target,
+        staged: `${target}.fx-next-${token}`,
+        backup: `${target}.fx-old-${token}`,
+    };
+    await fs.writeFile(journal, JSON.stringify(tx), { flag: 'wx', mode: 0o600 });
+    try {
+        await fs.cp(source, tx.staged, { recursive: true, errorOnExist: true, force: false });
+        if (await exists(target))
+            await fs.rename(target, tx.backup);
+        await fs.rename(tx.staged, target);
+        await fs.rm(tx.backup, { recursive: true, force: true });
+        await fs.unlink(journal);
+    }
+    catch (err) {
+        await recover(target, journal);
+        throw err;
+    }
+}
+async function recover(target, journal) {
+    let raw;
+    try {
+        raw = await fs.readFile(journal, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    let tx;
+    try {
+        tx = JSON.parse(raw);
+    }
+    catch {
+        throw conflict();
+    }
+    if (tx?.target !== target ||
+        typeof tx.staged !== 'string' ||
+        typeof tx.backup !== 'string' ||
+        !tx.staged.startsWith(`${target}.fx-next-`) ||
+        !tx.backup.startsWith(`${target}.fx-old-`) ||
+        path.dirname(tx.staged) !== path.dirname(target) ||
+        path.dirname(tx.backup) !== path.dirname(target))
+        throw conflict();
+    if (!(await exists(target)) && (await exists(tx.backup)))
+        await fs.rename(tx.backup, target);
+    await fs.rm(tx.staged, { recursive: true, force: true });
+    await fs.rm(tx.backup, { recursive: true, force: true });
+    await fs.unlink(journal);
+}
+async function exists(file) {
+    try {
+        await fs.lstat(file);
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+}
+function conflict() {
+    return new DevkitError('conflict', 'PROJECTION_RECOVERY_REQUIRED', 'A directory projection has an unrecognized recovery record', {
+        hint: 'Inspect the transaction and preserve both directories before retrying.',
+        nextSteps: ['fx doctor'],
+    });
+}
+//# sourceMappingURL=directory-replacement.js.map

package/dist/adapters/fs/directory-replacement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-replacement.js","sourceRoot":"","sources":["../../../src/adapters/fs/directory-replacement.ts"],"names":[],"mappings":"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"}

package/dist/adapters/fs/node-fs.js

@@ -0,0 +1,223 @@
+// node:fs behind the FileSystem port, keeping the port's promise that absence
+// is a value: a missing file reads as undefined, a missing directory as empty,
+// a path that is no link as no link. Every write makes its parent directory
+// first. Anything else propagates.
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { asDevkitError, busyError, DevkitError } from '../../domain/errors.js';
+import { pathKey } from '../../domain/path.js';
+import { replaceDirectory } from './directory-replacement.js';
+export class NodeFs {
+    lock;
+    async ensureDir(directory) {
+        await fs.mkdir(directory, { recursive: true });
+    }
+    constructor(lock) {
+        this.lock = lock;
+    }
+    async readBytes(file) {
+        try {
+            return await fs.readFile(file);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return undefined;
+            throw err;
+        }
+    }
+    async writeBytes(file, bytes, executable = false) {
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, bytes, { mode: executable ? 0o755 : 0o644 });
+    }
+    async readText(file) {
+        try {
+            return await fs.readFile(file, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return undefined;
+            throw err;
+        }
+    }
+    async writeText(file, text) {
+        const lease = await this.lock?.acquire({
+            key: `projection:${pathKey(file)}`,
+            waitMs: 2000,
+        });
+        if (lease === null)
+            throw busyError('LOCK_BUSY', 'The projection');
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        try {
+            await fs.mkdir(path.dirname(file), { recursive: true });
+            const current = await fs.lstat(file).catch((err) => {
+                if (err.code === 'ENOENT')
+                    return undefined;
+                throw err;
+            });
+            if (current && !current.isFile())
+                throw new DevkitError('conflict', 'PROJECTION_FOREIGN', 'The projection is not a regular file', { nextSteps: [`Remove or rename ${file}, then re-run the same command.`] });
+            await fs.writeFile(temporary, text, {
+                flag: 'wx',
+                mode: current === undefined ? 0o600 : current.mode & 0o777,
+            });
+            await fs.rename(temporary, file);
+        }
+        finally {
+            await fs.rm(temporary, { force: true });
+            await lease?.release();
+        }
+    }
+    async replaceDir(from, to) {
+        if (!this.lock)
+            throw new DevkitError('internal', 'LOCK_UNAVAILABLE', 'Directory replacement requires a lock');
+        const lease = await this.lock.acquire({ key: `projection:${pathKey(to)}`, waitMs: 2000 });
+        if (!lease)
+            throw busyError('LOCK_BUSY', 'The Skill projection');
+        try {
+            const current = await fs.lstat(to).catch((err) => {
+                if (err.code === 'ENOENT')
+                    return undefined;
+                throw err;
+            });
+            if (current && !current.isDirectory())
+                throw new DevkitError('conflict', 'PROJECTION_FOREIGN', 'The projection is not a directory', { nextSteps: [`Remove or rename ${to}, then re-run the same command.`] });
+            await replaceDirectory(from, to);
+        }
+        catch (err) {
+            throw asDevkitError(err);
+        }
+        finally {
+            await lease.release();
+        }
+    }
+    async moveToBackup(target) {
+        if (!this.lock)
+            throw new DevkitError('internal', 'LOCK_UNAVAILABLE', 'Path replacement requires a lock');
+        const requested = path.resolve(target);
+        const parent = await fs.realpath(path.dirname(requested));
+        const file = path.join(parent, path.basename(requested));
+        const lease = await this.lock.acquire({ key: `projection:${pathKey(file)}`, waitMs: 2000 });
+        if (!lease)
+            throw busyError('LOCK_BUSY', 'The replacement');
+        try {
+            await assertBackupParent(requested, parent);
+            const current = await fs.lstat(file);
+            if (!current.isFile() && !current.isDirectory() && !current.isSymbolicLink())
+                throw new DevkitError('conflict', 'PROJECTION_FOREIGN', 'The path cannot be backed up', {
+                    nextSteps: [`Inspect ${file} and move it aside before retrying.`],
+                });
+            for (let suffix = 0;; suffix += 1) {
+                const backup = `${file}.fx-backup${suffix === 0 ? '' : `-${suffix}`}`;
+                const backupLease = await this.lock.acquire({
+                    key: `projection:${pathKey(backup)}`,
+                    waitMs: 0,
+                });
+                if (!backupLease)
+                    throw busyError('LOCK_BUSY', 'The backup');
+                try {
+                    if (await fs.lstat(backup).then(() => true, missingPath))
+                        continue;
+                    await assertBackupParent(requested, parent);
+                    // The move preserves saves through an open file handle; a later editor
+                    // replacement at the original path is left for the caller to recheck.
+                    await fs.rename(file, backup);
+                    return backup;
+                }
+                finally {
+                    await backupLease.release();
+                }
+            }
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                throw new DevkitError('conflict', 'PROJECTION_CHANGED', 'The replacement path changed', {
+                    nextSteps: [`Inspect ${file} and retry from its current state.`],
+                    cause: err,
+                });
+            throw asDevkitError(err);
+        }
+        finally {
+            await lease.release();
+        }
+    }
+    async exists(file) {
+        try {
+            await fs.access(file);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async readDir(dir) {
+        try {
+            return await fs.readdir(dir);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+    }
+    async isDirectory(dir) {
+        try {
+            return (await fs.stat(dir)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+    async readLink(file) {
+        try {
+            return await fs.readlink(file);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async link(target, at) {
+        await fs.mkdir(path.dirname(at), { recursive: true });
+        await fs.symlink(path.resolve(target), at, process.platform === 'win32' ? 'junction' : 'dir');
+    }
+    async copyDir(from, to) {
+        await fs.mkdir(path.dirname(to), { recursive: true });
+        await fs.cp(from, to, { recursive: true });
+    }
+    async remove(file) {
+        const stat = await fs.lstat(file).catch((err) => {
+            if (err.code !== 'ENOENT')
+                throw err;
+            return undefined;
+        });
+        if (stat?.isSymbolicLink()) {
+            await fs.unlink(file);
+            return;
+        }
+        await fs.rm(file, { recursive: true, force: true });
+    }
+    async realpath(target) {
+        try {
+            return await fs.realpath(target);
+        }
+        catch {
+            const absolute = path.resolve(target);
+            const parent = path.dirname(absolute);
+            return parent === absolute
+                ? absolute
+                : path.join(await this.realpath(parent), path.basename(absolute));
+        }
+    }
+}
+function missingPath(error) {
+    if (error.code === 'ENOENT')
+        return false;
+    throw error;
+}
+async function assertBackupParent(file, parent) {
+    if ((await fs.realpath(path.dirname(file))) !== parent)
+        throw new DevkitError('conflict', 'PROJECTION_CHANGED', 'The replacement directory changed', {
+            nextSteps: [`Inspect the directory containing ${file}, then retry.`],
+        });
+}
+//# sourceMappingURL=node-fs.js.map

package/dist/adapters/fs/node-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-fs.js","sourceRoot":"","sources":["../../../src/adapters/fs/node-fs.ts"],"names":[],"mappings":"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"}