@naswerks/periscope 1.0.0

package/dist/bin/pair.js

@@ -0,0 +1,198 @@
+/**
+ * `periscope pair <code> [--controller <origin>] [--label <name>]` — trade a short-lived pair code
+ * for this machine's durable credential, and learn where the controller is from its answer.
+ *
+ * Why this is a command rather than something the daemon does: the same reason `login` is. The
+ * code is single-use and expires in minutes (it is a deliberate act a person performs once) and
+ * the daemon must never block on anything interactive. After this succeeds, the daemon reads the
+ * written file forever; after the controller revokes it, the daemon's next dial dies loudly and
+ * the fix is to run this again with a fresh code.
+ *
+ * It writes the same protected directory the daemon reads, derived from the same call:
+ * `pairedCredentialPath(env)`, beside the token cache, inside the gate's protected set. Nothing
+ * here computes a path of its own.
+ *
+ * Where the redemption door is: `--controller`'s origin when given; else `PERISCOPE_PAIR_URL` when
+ * set; otherwise derived from `PERISCOPE_DECISION_URL`'s origin (the one controller URL every
+ * configured host already has) plus the controller's published redemption route. The derivation is
+ * stated here once so a controller that moves the route has one line to argue with.
+ *
+ * What the controller answers with, beyond the credential: the URLs this host should dial
+ * (`controllerUrl`, `decisionUrl`). The controller names its own routes; this command hardcodes only
+ * the pair route above. When both arrive they are written to the config file beside the credential,
+ * so a machine paired with one command needs nothing else before `serve`. The environment still
+ * wins per key, and the write says so when it is shadowed.
+ */
+import { certificateRemedy, describeFailure, isCertificateRefusal } from '../core/failure.js';
+import { writeConfigEntries } from '../host/config-file.js';
+import { readMachineFacts } from '../host/machine.js';
+import { pairedCredentialPath } from '../host/paths.js';
+import { FilePairedCredential } from '../host/paired-credential-store.js';
+const REDEMPTION_ROUTE = '/api/periscope/pair';
+/** Run the pair command. Returns rather than exits, so the caller owns the process. */
+export async function runPair(code, env, deps = {}, asked = {}) {
+    const write = deps.write ?? ((line) => process.stdout.write(`${line}\n`));
+    if (code === null) {
+        return {
+            ok: false,
+            detail: 'no code given - usage: periscope pair <code> [--controller <origin>] [--label <name>]',
+        };
+    }
+    const url = redemptionUrl(env, asked.controller ?? null);
+    if (url === null) {
+        return {
+            ok: false,
+            detail: asked.controller === undefined || asked.controller === null
+                ? 'nowhere to redeem the code - pass --controller <origin>, or set PERISCOPE_PAIR_URL or PERISCOPE_DECISION_URL (whose origin names the controller)'
+                : `--controller '${asked.controller}' is not an http(s) URL`,
+        };
+    }
+    const path = pairedCredentialPath(env);
+    if (path === null) {
+        return {
+            ok: false,
+            detail: 'nowhere to keep the credential - set PERISCOPE_CONFIG_DIR or run as a user with a home directory',
+        };
+    }
+    // The label the operator will recognize this machine by in every listing. Overridable because a
+    // hostname like `DESKTOP-4F7Q2` recognizes nobody.
+    const machineLabel = asked.label ?? env['PERISCOPE_MACHINE_LABEL'] ?? readMachineFacts().hostname;
+    const transport = deps.transport ?? fetch;
+    let response;
+    try {
+        response = await transport(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ code, machineLabel }),
+        });
+    }
+    catch (error) {
+        // The cause, not the wrapper: `fetch failed` over a refused certificate is not "unreachable", and
+        // a reader told the controller is down will not look at the certificate.
+        const why = describeFailure(error);
+        return {
+            ok: false,
+            detail: isCertificateRefusal(error)
+                ? `the controller at ${url} presented a certificate Node refused (${why}). ${certificateRemedy('the controller')}`
+                : `the controller at ${url} could not be reached - ${why}`,
+        };
+    }
+    if (response.status === 404 || response.status === 405) {
+        // Nothing at this route is a wrong door, not a refused code: the origin is not a controller,
+        // or its pair route is elsewhere. Saying "mint a fresh code" here sends the reader to the
+        // wrong fix.
+        return {
+            ok: false,
+            detail: `nothing answers the pair route at ${url} (HTTP ${response.status}). Check --controller (an ` +
+                'http(s) origin) or PERISCOPE_PAIR_URL; a controller redeems codes at its own pair route.',
+        };
+    }
+    if (!response.ok) {
+        // The door's one refusal is deliberate (unknown, expired and consumed answer identically);
+        // the honest instruction is therefore always the same: mint a fresh code.
+        const body = await response.text().catch(() => '');
+        return {
+            ok: false,
+            detail: `the controller refused this code (HTTP ${response.status}${body === '' ? '' : ` - ${body}`}). ` +
+                'Codes are single-use and expire in minutes; mint a fresh one and try again.',
+        };
+    }
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch {
+        return {
+            ok: false,
+            detail: 'the controller answered success with an unreadable body - nothing was written',
+        };
+    }
+    const record = (typeof parsed === 'object' && parsed !== null ? parsed : {});
+    const hostId = record['hostId'];
+    const credential = record['hostCredential'];
+    if (typeof hostId !== 'string' || hostId === '' || typeof credential !== 'string' || credential === '') {
+        return {
+            ok: false,
+            detail: 'the controller answered success without a credential - nothing was written',
+        };
+    }
+    // The shape is the contract: `serve` reads the host id out of the credential and refuses a file
+    // whose two copies disagree, so a credential that would be refused at the next start is refused
+    // here, where the fix (the controller's answer) is nameable.
+    if (!credential.startsWith(`p1.${hostId}.`) || credential.length <= `p1.${hostId}.`.length) {
+        return {
+            ok: false,
+            detail: `the controller answered a credential that does not have the shape p1.<hostId>.<secret> for ` +
+                `host ${hostId} - nothing was written. A paired credential embeds the host id it speaks for.`,
+        };
+    }
+    const store = (deps.store ?? ((p) => new FilePairedCredential(p)))(path);
+    const written = store.write({ hostId, credential });
+    if (!written.ok) {
+        return { ok: false, detail: `${written.refusal.reason} - ${written.refusal.detail}` };
+    }
+    write(`paired as ${hostId}; credential written to ${path}`);
+    write('this host now dials with the paired credential - the sign-in token expiry no longer applies to it');
+    // The controller names where this host should dial. Written after the credential, never instead
+    // of it: the credential is the scarce thing, and a config write that fails is reported, not a
+    // reason to lose what was just minted.
+    const controllerUrl = record['controllerUrl'];
+    const decisionUrl = record['decisionUrl'];
+    if (typeof controllerUrl === 'string' &&
+        controllerUrl !== '' &&
+        typeof decisionUrl === 'string' &&
+        decisionUrl !== '') {
+        const problem = writeConfigEntries(env, [
+            { key: 'PERISCOPE_CONTROLLER_URL', value: controllerUrl },
+            { key: 'PERISCOPE_DECISION_URL', value: decisionUrl },
+        ]);
+        if (problem !== null) {
+            write(`the controller's addresses were not written to the config file - ${problem}`);
+        }
+        else {
+            write(`PERISCOPE_CONTROLLER_URL and PERISCOPE_DECISION_URL written to the config file - serve needs nothing else`);
+            for (const key of ['PERISCOPE_CONTROLLER_URL', 'PERISCOPE_DECISION_URL']) {
+                const fromEnv = env[key];
+                if (fromEnv !== undefined && fromEnv !== '') {
+                    write(`note: ${key} is set in the environment, and the environment wins - the file value is a fallback`);
+                }
+            }
+        }
+    }
+    else {
+        write('the controller did not name its link and decision URLs - set PERISCOPE_CONTROLLER_URL and PERISCOPE_DECISION_URL before serve');
+    }
+    return { ok: true, hostId, path };
+}
+/**
+ * The redemption door's address. `PERISCOPE_PAIR_URL` verbatim when set; otherwise the decision
+ * URL's origin + the controller's published route. The decision URL is required configuration for
+ * every serving host, so a machine being paired on the box it will serve from has nothing extra to
+ * set.
+ */
+function redemptionUrl(env, controller) {
+    if (controller !== null) {
+        try {
+            const parsed = new URL(controller);
+            if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+                return null;
+            return `${parsed.origin}${REDEMPTION_ROUTE}`;
+        }
+        catch {
+            return null;
+        }
+    }
+    const explicit = env['PERISCOPE_PAIR_URL'];
+    if (explicit !== undefined && explicit !== '')
+        return explicit;
+    const decision = env['PERISCOPE_DECISION_URL'];
+    if (decision === undefined || decision === '')
+        return null;
+    try {
+        return `${new URL(decision).origin}${REDEMPTION_ROUTE}`;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=pair.js.map

package/dist/bin/periscope.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=periscope.d.ts.map

package/dist/bin/periscope.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main, processIo } from './main.js';
+void main(process.argv.slice(2), process.env, processIo());
+//# sourceMappingURL=periscope.js.map

package/dist/bin/posture.d.ts

@@ -0,0 +1,64 @@
+import type { LinkStateRecord } from '../host/link-state-file.js';
+import type { CredentialPosture } from './serve.js';
+export interface PostureInputs {
+    /** The process environment as it was. */
+    readonly raw: NodeJS.ProcessEnv;
+    /** The environment with the config file filling its absences. */
+    readonly merged: NodeJS.ProcessEnv;
+    /** The values the config file holds, so a key can say which source it came from. */
+    readonly fileValues: Readonly<Record<string, string>>;
+    /** What `readCredential` decided, or its refusal. */
+    readonly credential: CredentialPosture | string;
+    /** The cached token's expiry in epoch milliseconds, when a token cache is readable. */
+    readonly tokenExpiresAtMs: number | null;
+    readonly nowMs: number;
+    readonly link: LinkStateRecord | null;
+    /** Whether the process that wrote the link record is still alive. */
+    readonly pidAlive: (pid: number) => boolean;
+    /** The machine's hostname, the host id's fallback. */
+    readonly hostname: string;
+}
+export type CredentialKind = 'paired' | 'token' | 'absent' | 'unreadable';
+export type WorkspaceMode = 'git-worktree' | 'plain' | 'none';
+export type Source = 'environment' | 'config-file' | 'default' | 'unset';
+export interface Setting {
+    readonly key: string;
+    readonly value: string | null;
+    readonly source: Source;
+    /** Set in both places, and the environment won. */
+    readonly shadowsFile: boolean;
+}
+export interface Posture {
+    readonly hostId: {
+        readonly configured: string;
+        readonly paired: string | null;
+        readonly effective: string;
+    };
+    readonly credential: {
+        readonly kind: CredentialKind;
+        readonly expiresAt: string | null;
+        readonly expired: boolean;
+        readonly problem: string | null;
+    };
+    readonly workspace: {
+        readonly mode: WorkspaceMode;
+        readonly branchScheme: string | null;
+    };
+    readonly sources: readonly Setting[];
+    readonly configFile: string | null;
+    readonly link: {
+        readonly state: string;
+        readonly cause: string | null;
+        readonly at: string | null;
+        readonly detail: string | null;
+        readonly negotiatedVersion: number | null;
+        readonly pid: number | null;
+        readonly alive: boolean;
+    };
+}
+export declare function describePosture(inputs: PostureInputs): Posture;
+/** The one line `serve` prints at start-up: the host, the credential, the workspace, the config file. */
+export declare function postureLine(posture: Posture): string;
+/** The whole posture, one fact per line, for `periscope status`. */
+export declare function renderPosture(posture: Posture): string[];
+//# sourceMappingURL=posture.d.ts.map

package/dist/bin/posture.js

@@ -0,0 +1,157 @@
+/**
+ * What this host is, said once: its ids, its credential, its workspace, its link and where each
+ * setting came from. `serve` prints the one-line form at start-up and `status` prints the whole,
+ * from one description, so the two can never disagree about the host they describe. Pure over its
+ * inputs; the reads that fill them live with the verbs.
+ */
+import { CONFIG_KEYS, WIRE_CONFIGURABLE_KEYS, configFilePath } from '../host/config-file.js';
+import { workspaceCapabilitiesOf } from './workspaces.js';
+function settingOf(key, inputs) {
+    const fromEnv = inputs.raw[key];
+    const fromFile = inputs.fileValues[key];
+    const inEnv = fromEnv !== undefined && fromEnv !== '';
+    const inFile = fromFile !== undefined && fromFile !== '';
+    if (inEnv)
+        return { key, value: fromEnv, source: 'environment', shadowsFile: inFile };
+    if (inFile)
+        return { key, value: fromFile, source: 'config-file', shadowsFile: false };
+    const merged = inputs.merged[key];
+    if (merged !== undefined && merged !== '')
+        return { key, value: merged, source: 'default', shadowsFile: false };
+    return { key, value: null, source: 'unset', shadowsFile: false };
+}
+export function describePosture(inputs) {
+    const keys = [
+        ...new Set([
+            ...CONFIG_KEYS,
+            ...WIRE_CONFIGURABLE_KEYS,
+            'PERISCOPE_HOST_ID',
+            'PERISCOPE_CONFIG_DIR',
+        ]),
+    ];
+    const sources = keys.map((key) => settingOf(key, inputs));
+    const value = (key) => sources.find((one) => one.key === key)?.value ?? null;
+    const configured = value('PERISCOPE_HOST_ID') ?? inputs.hostname;
+    const paired = typeof inputs.credential === 'string' ? null : inputs.credential.pairedHostId;
+    let kind;
+    let problem = null;
+    if (typeof inputs.credential === 'string') {
+        kind = 'unreadable';
+        problem = inputs.credential;
+    }
+    else if (inputs.credential.pairedHostId !== null)
+        kind = 'paired';
+    else if (inputs.credential.credential !== null)
+        kind = 'token';
+    else
+        kind = 'absent';
+    const expiresAt = kind === 'token' && inputs.tokenExpiresAtMs !== null
+        ? new Date(inputs.tokenExpiresAtMs).toISOString()
+        : null;
+    const expired = kind === 'token' && inputs.tokenExpiresAtMs !== null && inputs.tokenExpiresAtMs <= inputs.nowMs;
+    const capabilities = workspaceCapabilitiesOf({
+        workspaceRoot: value('PERISCOPE_WORKSPACE_ROOT'),
+        repositoryRoot: value('PERISCOPE_REPOSITORY_ROOT'),
+        branchScheme: value('PERISCOPE_BRANCH_SCHEME'),
+    });
+    const mode = capabilities.includes('workspace:git-worktree')
+        ? 'git-worktree'
+        : capabilities.includes('workspace:plain')
+            ? 'plain'
+            : 'none';
+    const link = inputs.link;
+    return {
+        hostId: { configured, paired, effective: paired ?? configured },
+        credential: { kind, expiresAt, expired, problem },
+        workspace: { mode, branchScheme: value('PERISCOPE_BRANCH_SCHEME') },
+        sources,
+        configFile: configFilePath(inputs.raw),
+        link: link === null
+            ? {
+                state: 'unknown',
+                cause: null,
+                at: null,
+                detail: null,
+                negotiatedVersion: null,
+                pid: null,
+                alive: false,
+            }
+            : {
+                state: link.state,
+                cause: link.cause,
+                at: link.at,
+                detail: link.detail,
+                negotiatedVersion: link.negotiatedVersion,
+                pid: link.pid,
+                alive: inputs.pidAlive(link.pid),
+            },
+    };
+}
+/** The one line `serve` prints at start-up: the host, the credential, the workspace, the config file. */
+export function postureLine(posture) {
+    // A token posture names the cache it will present: configured for a token with none cached is
+    // the state every refusal at the first dial comes from, and it is visible here first.
+    const credential = posture.credential.kind === 'token'
+        ? posture.credential.expiresAt !== null
+            ? `token (expires ${posture.credential.expiresAt})`
+            : 'token (no cache yet - sign in first)'
+        : posture.credential.kind;
+    return (`host ${posture.hostId.effective}` +
+        (posture.hostId.paired !== null && posture.hostId.paired !== posture.hostId.configured
+            ? ` (paired; configured ${posture.hostId.configured})`
+            : '') +
+        ` · credential ${credential} · workspace ${posture.workspace.mode}` +
+        ` · config file ${posture.configFile ?? '(none)'}`);
+}
+/** The whole posture, one fact per line, for `periscope status`. */
+export function renderPosture(posture) {
+    const lines = [];
+    const link = posture.link;
+    if (link.state === 'unknown') {
+        lines.push('link: unknown — no host has started with this config directory yet; run periscope to start one');
+    }
+    else {
+        const liveness = link.alive
+            ? `serve pid ${link.pid} is running`
+            : `serve pid ${link.pid} is gone, so this is the last thing it said`;
+        lines.push(`link: ${link.state} since ${link.at} (${link.cause}${link.detail === null ? '' : `: ${link.detail}`}); ${liveness}`);
+        if (link.negotiatedVersion !== null)
+            lines.push(`protocol: v${link.negotiatedVersion} negotiated at the last accepted handshake`);
+    }
+    const credential = posture.credential;
+    switch (credential.kind) {
+        case 'paired':
+            lines.push(`credential: paired as ${posture.hostId.paired} (no expiry; rotation is re-pairing)`);
+            break;
+        case 'token':
+            lines.push(`credential: signed-in token${credential.expiresAt === null ? ' (no cache yet - run periscope login)' : `, ${credential.expired ? 'EXPIRED at' : 'expires'} ${credential.expiresAt}`}`);
+            break;
+        case 'absent':
+            lines.push('credential: absent — this host dials without authentication');
+            break;
+        default:
+            lines.push(`credential: unreadable — ${credential.problem ?? ''}`);
+    }
+    lines.push(`host id: ${posture.hostId.effective}` +
+        (posture.hostId.paired !== null
+            ? posture.hostId.paired === posture.hostId.configured
+                ? ' (the paired credential agrees)'
+                : ` (the paired credential's, overriding the configured ${posture.hostId.configured})`
+            : ''));
+    lines.push(`workspace: ${posture.workspace.mode}${posture.workspace.branchScheme === null ? '' : `, branch scheme ${posture.workspace.branchScheme}`}`);
+    lines.push(`config file: ${posture.configFile ?? '(none: no home directory and no PERISCOPE_CONFIG_DIR)'}`);
+    for (const setting of posture.sources) {
+        // The config directory is never a config-file key (a file cannot move itself), so it is listed
+        // only when the environment set it.
+        if (setting.key === 'PERISCOPE_CONFIG_DIR' && setting.source === 'unset')
+            continue;
+        const where = setting.source === 'environment'
+            ? setting.shadowsFile
+                ? 'environment, shadowing the config file'
+                : 'environment'
+            : setting.source;
+        lines.push(`  ${setting.key} = ${setting.value ?? '(unset)'}  [${where}]`);
+    }
+    return lines;
+}
+//# sourceMappingURL=posture.js.map

package/dist/bin/reconfigure.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A configuration change asked over the wire (`host_configure`, protocol v7): validate, write,
+ * rebuild.
+ *
+ * Split out of the composition root for the reason `workspaces.ts` gives: everything below the
+ * composition root takes its configuration as arguments, and this is the one function that
+ * reads the config file, screens a candidate posture and builds the pieces the host swaps in. It
+ * is called with the RAW environment because the file fills absences in it (`withConfigFallback`),
+ * and the same rule that governs `serve` governs a change made while serving: the environment
+ * wins per key, so a value this writes that the environment shadows is reported as overridden,
+ * never silently inert.
+ *
+ * Nothing is written until the whole candidate posture has passed the same screen start-up runs,
+ * so a half-applied set never lands on disk; and a change to a workspace root is refused while the
+ * host is busy, because a session releases through the provider that provisioned it.
+ */
+import type { HostConfigureEntry } from '../control/frames.js';
+import type { Result } from '../core/result.js';
+import type { HostReconfigured } from '../host/host.js';
+/** The effective posture a merged environment describes, with absence as null. */
+interface EffectivePosture {
+    readonly workspaceRoot: string | null;
+    readonly repositoryRoot: string | null;
+    readonly branchScheme: string | null;
+    readonly workspaceKey: string | null;
+    readonly agentHome: string | null;
+    readonly controllerUrl: string | null;
+    readonly decisionUrl: string | null;
+}
+/**
+ * The control-plane addresses the running host actually uses: what it dialled at start. A file
+ * value that differs is written and reported as pending, never applied to the live link.
+ */
+export interface LiveAddresses {
+    readonly controllerUrl: string | null;
+    readonly decisionUrl: string | null;
+}
+/**
+ * Why a control-plane address cannot be written, or null. The link is dialled as a WebSocket and
+ * the decision endpoint is POSTed to, so each key takes the schemes its act can use and nothing
+ * else: a value that fits the other key would fail at the first act after the restart it waits for.
+ */
+/**
+ * The first thing wrong with ONE value for ONE key, or null: the per-key half of `candidateProblem`,
+ * shared with `periscope config` and the daemon's start-up read so a value the wire would refuse is
+ * refused wherever it is typed. A key this screen does not know passes; the closed key set is
+ * checked by the writer.
+ */
+export declare function configValueProblem(key: string, value: string): string | null;
+/** The wire-settable keys the environment sets: their file values are unreachable. */
+export declare function overriddenByEnvironment(raw: NodeJS.ProcessEnv): readonly string[];
+/**
+ * The first thing wrong with a candidate posture, or null. The same screen start-up runs
+ * (`workspacePostureProblem`) plus the rules the wire needs that start-up gets from the shell: a
+ * root must be absolute, and a scheme must render distinct branches (contain `{key}`).
+ */
+export declare function candidateProblem(posture: EffectivePosture): string | null;
+/**
+ * Apply the entries: screen every key, screen the candidate posture as a whole, refuse a roots
+ * change while busy, write the file once, and rebuild what the host swaps in.
+ */
+export declare function reconfigureHost(raw: NodeJS.ProcessEnv, entries: readonly HostConfigureEntry[], hostBusy: boolean, live?: LiveAddresses): Result<HostReconfigured>;
+export {};
+//# sourceMappingURL=reconfigure.d.ts.map