@north-light/crouter 0.3.164 → 0.3.166

package/dist/core/configured-clis/discovery.js

@@ -1,173 +0,0 @@
-// Configured-CLI discovery — the single integration seam that joins effective
-// registrations, their STORED manifest bytes, pure §4 validation, and configured
-// contribution creation, then folds the result together with command-plugin
-// candidates into ONE unified, collision-resolved command snapshot.
-//
-// This is the serial integration point (E1). Three consumers read the exact same
-// final snapshot so their view of accepted commands and issues can never drift:
-//   - dispatch / root composition (build-root.ts) via `buildExternalCommandSnapshot`
-//   - `pkg cli show` + `pkg plugin show` (lifecycle inspection)
-//   - `sys doctor`
-//
-// Two hard invariants of the amended spec:
-//   1. Composition from a stored manifest does ZERO network and ZERO freshness
-//      work — no TTL, no ETag, no revalidation, no debounce. The bytes on disk
-//      are authoritative until a `register`/`refresh` replaces them.
-//   2. The ONLY network this module can trigger is `hydrateAbsentConfiguredClis`,
-//      the one-time absent-store hydration on an unknown-first-token miss (§5.1).
-//      It is exported separately so dispatch (E2) can call it explicitly; nothing
-//      on the composition path ever fetches.
-import { resolveCommandRegistry } from '../command-manifests/registry.js';
-import { adaptPluginContributions } from '../command-plugins/compose.js';
-import { discoverPluginCommandCandidates } from '../command-plugins/discovery.js';
-import { validateConfiguredCliManifest } from './manifest.js';
-import { effectiveConfiguredClis } from './registration.js';
-import { isCacheMetadataValid, readConfiguredCliCacheManifest, writeConfiguredCliCacheManifest } from './cache.js';
-import { fetchConfiguredCliManifest } from './fetch.js';
-import { adaptConfiguredContributions } from './compose.js';
-function contributorRef(registration) {
-    return { kind: 'configured-cli', name: registration.name, scope: registration.scope };
-}
-/** Read + validate a registration's STORED manifest. Never fetches. A missing,
- *  metadata-mismatched, or unparseable manifest reads as `absent` (§3.3: corrupt
- *  or incomplete stored state reads as absent, making it hydration-eligible). A
- *  parseable manifest that fails §4 validation is `invalid` (stored, reports
- *  issues, composes nothing — NOT hydration-eligible). */
-function readStoredManifest(registration, reservedCoreNames) {
-    if (!isCacheMetadataValid(registration))
-        return { state: 'absent' };
-    const bytes = readConfiguredCliCacheManifest(registration);
-    if (bytes === null)
-        return { state: 'absent' };
-    let raw;
-    try {
-        raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
-    }
-    catch {
-        return { state: 'absent' }; // unparseable → reads as absent
-    }
-    const validation = validateConfiguredCliManifest(raw, { reservedCoreNames });
-    if (validation.manifest !== undefined)
-        return { state: 'valid', manifest: validation.manifest };
-    return {
-        state: 'invalid',
-        issues: validation.issues.map((i) => ({ ...i, contributor: contributorRef(registration) })),
-    };
-}
-/** Discover configured-CLI candidates from stored manifests only — zero network.
- *  Each effective registration (project over user) contributes its valid roots,
- *  reports its invalid-manifest issues, or is noted as absent-store. */
-export function discoverConfiguredCliCandidates(reservedCoreNames) {
-    const candidates = [];
-    const issues = [];
-    const absentStoreNames = [];
-    for (const registration of effectiveConfiguredClis()) {
-        const stored = readStoredManifest(registration, reservedCoreNames);
-        if (stored.state === 'absent') {
-            absentStoreNames.push(registration.name);
-        }
-        else if (stored.state === 'invalid') {
-            issues.push(...stored.issues);
-        }
-        else {
-            candidates.push(...adaptConfiguredContributions(registration, stored.manifest));
-        }
-    }
-    return { candidates, issues, absentStoreNames };
-}
-// ---------------------------------------------------------------------------
-// The one unified snapshot (zero network)
-// ---------------------------------------------------------------------------
-/** Convert command-plugin candidates + their per-plugin structural issues into
- *  the transport-neutral shape, WITHOUT the plugin module's own collision pass
- *  (collisions are resolved once, uniformly, by `resolveCommandRegistry`). */
-function pluginCandidates() {
-    const validations = discoverPluginCommandCandidates();
-    // Reuse the plugin adapter purely to bind each ValidatedContribution's leaf to
-    // its executable-spawn `run`; the registry does the collision resolution.
-    const candidates = adaptPluginContributions(validations.flatMap((v) => v.contributions)).contributions;
-    const issues = validations.flatMap((v) => v.issues.map((i) => ({
-        code: i.code,
-        ...(i.path !== undefined ? { path: i.path } : {}),
-        message: i.message,
-        received: i.received,
-        expected: i.expected,
-        next: i.next,
-        // Command plugins are never installed at builtin scope.
-        contributor: { kind: 'plugin', name: v.plugin.name, scope: v.plugin.scope },
-    })));
-    return { candidates, issues };
-}
-/** Build THE unified external-command snapshot: every effective command plugin
- *  and every effective configured CLI, resolved through ONE collision pass, with
- *  every issue (plugin-structural, configured-manifest-invalid, and cross-
- *  contributor collision) merged into one list. Performs zero network I/O — all
- *  manifests read from disk. This exact result is consumed by dispatch/root
- *  composition, `pkg cli show`/`pkg plugin show`, and `sys doctor`, so their
- *  accepted-command and issue views can never diverge. `reservedCoreNames` are
- *  the core top-level subtree names — core always wins. */
-export function buildExternalCommandSnapshot(reservedCoreNames) {
-    const plugins = pluginCandidates();
-    const configured = discoverConfiguredCliCandidates(reservedCoreNames);
-    const resolved = resolveCommandRegistry([...plugins.candidates, ...configured.candidates], reservedCoreNames);
-    return {
-        contributions: resolved.contributions,
-        issues: [...plugins.issues, ...configured.issues, ...resolved.issues],
-    };
-}
-/** Is this registration's stored manifest absent (hydration-eligible)? Mirrors
- *  `readStoredManifest`'s absent branch without running the full §4 validator —
- *  a parseable-but-invalid manifest is stored, not absent. */
-function isAbsentStore(registration) {
-    if (!isCacheMetadataValid(registration))
-        return true;
-    const bytes = readConfiguredCliCacheManifest(registration);
-    if (bytes === null)
-        return true;
-    try {
-        JSON.parse(Buffer.from(bytes).toString('utf8'));
-        return false;
-    }
-    catch {
-        return true; // unparseable → reads as absent
-    }
-}
-/** Hydrate EVERY effective absent-store registration exactly once (§5.1). For
- *  each registration with no readable stored manifest, perform one authenticated
- *  `GET endpoint`, storing the exact bytes on success. A fetch failure (network,
- *  non-2xx, or named-but-empty auth env) leaves the store absent and records a
- *  one-line diagnostic — it never throws and never earns NETWORK precedence over
- *  the caller's `unknown_path`/USAGE classification. Registrations that already
- *  hold a stored manifest (valid OR merely schema-invalid) are skipped, so with
- *  every manifest stored this performs zero network I/O.
- *
- *  Intended caller: dispatch (E2), on an unknown-first-token miss, followed by a
- *  single tree rebuild + re-resolve when `hydratedAny` is true. */
-export async function hydrateAbsentConfiguredClis() {
-    let hydratedAny = false;
-    const diagnostics = [];
-    for (const registration of effectiveConfiguredClis()) {
-        if (!isAbsentStore(registration))
-            continue;
-        // A per-registration fetch OR store failure (network, non-2xx, empty auth
-        // env, or a filesystem write error) is a FAILED hydration for this one
-        // registration: record a diagnostic and continue. It must never throw and
-        // never earn NETWORK precedence over the caller's unknown_path/USAGE
-        // outcome (§5.1), so the whole attempt — including the atomic store — is
-        // caught here.
-        try {
-            const result = await fetchConfiguredCliManifest(registration);
-            if (result.status === 200) {
-                writeConfiguredCliCacheManifest(registration, result.raw);
-                hydratedAny = true;
-            }
-            else {
-                diagnostics.push(`configured CLI "${registration.name}": ${result.message} — run \`crtr pkg cli refresh ${registration.name}\``);
-            }
-        }
-        catch (error) {
-            diagnostics.push(`configured CLI "${registration.name}": ${error.message} — run \`crtr pkg cli refresh ${registration.name}\``);
-        }
-    }
-    return { hydratedAny, diagnostics };
-}

package/dist/core/configured-clis/manifest.d.ts

@@ -1,24 +0,0 @@
-import type { ConfiguredCliDeclLeaf, DeclBranch, ManifestTimeouts, CommandManifestIssue } from '../command-manifests/schema.js';
-export interface ValidatedConfiguredCliManifest {
-    schemaVersion: 1;
-    baseUrl?: string;
-    timeouts?: ManifestTimeouts;
-    /** Top-level branches, each ready to mount at parent []. */
-    roots: DeclBranch<ConfiguredCliDeclLeaf>[];
-}
-export interface ConfiguredCliManifestValidation {
-    /** The validated, materialized manifest (present only if all issues are fixed). */
-    manifest?: ValidatedConfiguredCliManifest;
-    /** All typed validation issues. Any issue means zero contributions. */
-    issues: CommandManifestIssue[];
-}
-/**
- * Validates a configured CLI manifest exactly per §4, performing strict atomic
- * validation and order-independent forest materialization. Returns either a
- * valid manifest with roots ready to mount, or a complete issues list with
- * zero contributions.
- */
-export declare function validateConfiguredCliManifest(raw: unknown, options: {
-    reservedCoreNames: ReadonlySet<string>;
-}): ConfiguredCliManifestValidation;
-export { validateConfiguredCliNode } from '../command-manifests/schema.js';

package/dist/core/configured-clis/registration.d.ts

@@ -1,40 +0,0 @@
-import type { Scope } from '../../types.js';
-/** A registered configured CLI: name, endpoint, optional auth env var, scope and root. */
-export interface ConfiguredCliRegistration {
-    name: string;
-    endpoint: string;
-    authEnvVar?: string;
-    scope: 'project' | 'user';
-    root: string;
-}
-/** Validation result for registration inputs. */
-export interface RegistrationValidation {
-    isValid: boolean;
-    errors: string[];
-}
-/** Validate a registration name. */
-export declare function validateRegistrationName(name: unknown): RegistrationValidation;
-/** Validate an environment variable name. */
-export declare function validateEnvVarName(name: unknown): RegistrationValidation;
-/** Validate an endpoint URL. */
-export declare function validateEndpoint(endpoint: unknown): RegistrationValidation;
-/** Normalize endpoint URL to a canonical form (remove trailing slash if present). */
-export declare function normalizeEndpoint(endpoint: string): string;
-/** List every EFFECTIVE configured CLI visible across scopes (project nearest-first,
- *  then user). Dedupes by name: the first-seen registration for a name wins (nearer
- *  project root, then user) and any same-name registration in a farther scope is
- *  omitted entirely — there is no shadowed-copy representation and no `effective`
- *  field on `ConfiguredCliRegistration`. */
-export declare function listConfiguredCliRegistrations(): ConfiguredCliRegistration[];
-/** Get deduplicated effective registrations (one per unique name, project wins over user). */
-export declare function effectiveConfiguredClis(): ConfiguredCliRegistration[];
-/** Resolve a configured CLI registration by name. If scope is omitted, returns the
- *  effective winner (project > user). If scope is explicit, returns the registration
- *  in that scope or null if not found. */
-export declare function resolveConfiguredCli(name: string, scope?: Scope | 'project' | 'user'): ConfiguredCliRegistration | null;
-/** Get the cache directory for a configured CLI registration. */
-export declare function configuredCliCacheDir(registration: ConfiguredCliRegistration): string;
-/** Get the manifest file path for a configured CLI. */
-export declare function configuredCliManifestPath(registration: ConfiguredCliRegistration): string;
-/** Get the cache metadata file path for a configured CLI. */
-export declare function configuredCliCacheMetaPath(registration: ConfiguredCliRegistration): string;

package/dist/core/configured-clis/registration.js

@@ -1,201 +0,0 @@
-import { join } from 'node:path';
-import { configuredClisDir, configuredClisDirForRoot, projectScopeRoots, userScopeRoot } from '../scope.js';
-import { readConfig, readConfigAtRoot } from '../config.js';
-/** Kebab-case identifier: lowercase letter start, alphanumeric + hyphen chars,
- *  no trailing hyphens. Examples: `demo`, `my-cli`, `azure-devops`. */
-function isValidRegistrationName(name) {
-    return /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(name);
-}
-/** Environment variable name: must start with letter or underscore, followed by
- *  alphanumeric or underscore chars. Examples: `NL_CORE_TOKEN`, `_INTERNAL`. */
-function isValidEnvVarName(name) {
-    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name);
-}
-/** Loopback hostnames permitted for plain-http endpoints (local dev only).
- *  Includes `host.docker.internal`, Docker's own DNS alias a container uses to
- *  reach its host — the container-network equivalent of loopback for the same
- *  local-dev trust boundary (e.g. a Dockerized guest registering its host
- *  Core as a configured CLI). */
-function isLoopbackHostname(hostname) {
-    // URL normalizes IPv6 hosts to bracketed form, e.g. `[::1]`.
-    return (hostname === 'localhost' ||
-        hostname === '127.0.0.1' ||
-        hostname === '[::1]' ||
-        hostname === '::1' ||
-        hostname === 'host.docker.internal');
-}
-/** Validate that endpoint is an absolute HTTPS URL (or HTTP on a loopback host)
- *  with no credentials/fragment. */
-function isValidEndpoint(endpoint) {
-    try {
-        const url = new URL(endpoint);
-        // https required; plain http permitted only for loopback hosts (local dev)
-        if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopbackHostname(url.hostname)))
-            return false;
-        if (url.username || url.password || url.hash)
-            return false;
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/** Validate a registration name. */
-export function validateRegistrationName(name) {
-    const errors = [];
-    if (typeof name !== 'string') {
-        errors.push('name must be a string');
-    }
-    else if (!isValidRegistrationName(name)) {
-        errors.push('name must be kebab-case (lowercase letter start, alphanumeric + hyphens)');
-    }
-    return { isValid: errors.length === 0, errors };
-}
-/** Validate an environment variable name. */
-export function validateEnvVarName(name) {
-    const errors = [];
-    if (typeof name !== 'string') {
-        errors.push('env var name must be a string');
-    }
-    else if (!isValidEnvVarName(name)) {
-        errors.push('env var name must start with letter/underscore, followed by alphanumeric/underscore');
-    }
-    return { isValid: errors.length === 0, errors };
-}
-/** Validate an endpoint URL. */
-export function validateEndpoint(endpoint) {
-    const errors = [];
-    if (typeof endpoint !== 'string') {
-        errors.push('endpoint must be a string');
-    }
-    else if (!isValidEndpoint(endpoint)) {
-        errors.push('endpoint must be an absolute https:// URL (http:// permitted for loopback hosts only; no credentials or fragment)');
-    }
-    return { isValid: errors.length === 0, errors };
-}
-/** Normalize endpoint URL to a canonical form (remove trailing slash if present). */
-export function normalizeEndpoint(endpoint) {
-    try {
-        const url = new URL(endpoint);
-        // Reconstruct without trailing slash on path
-        let pathname = url.pathname;
-        if (pathname.length > 1 && pathname.endsWith('/')) {
-            pathname = pathname.slice(0, -1);
-        }
-        return `${url.protocol}//${url.host}${pathname}${url.search}`;
-    }
-    catch {
-        return endpoint;
-    }
-}
-/** List every EFFECTIVE configured CLI visible across scopes (project nearest-first,
- *  then user). Dedupes by name: the first-seen registration for a name wins (nearer
- *  project root, then user) and any same-name registration in a farther scope is
- *  omitted entirely — there is no shadowed-copy representation and no `effective`
- *  field on `ConfiguredCliRegistration`. */
-export function listConfiguredCliRegistrations() {
-    const out = [];
-    const seen = new Set();
-    // Project scopes, nearest-first (projectScopeRoots is already nearest-first).
-    // Read EACH root's own config directly and address its own cache dir, so a
-    // nested/profile-widened stack keeps nearest-project precedence (first-seen
-    // wins) instead of collapsing every root onto the nearest config. `root` is
-    // the `configured-clis/` cache parent (matching resolveConfiguredCli and
-    // configuredCliCacheDir), never the bare scope-root.
-    for (const scopeRootDir of projectScopeRoots()) {
-        const config = readConfigAtRoot(scopeRootDir);
-        const root = configuredClisDirForRoot(scopeRootDir);
-        for (const [name, entry] of Object.entries(config.configuredClis)) {
-            if (seen.has(name))
-                continue;
-            out.push({
-                name,
-                endpoint: entry.endpoint,
-                authEnvVar: entry.authEnvVar,
-                scope: 'project',
-                root,
-            });
-            seen.add(name);
-        }
-    }
-    // Then user scope (lowest precedence, so add unseen ones).
-    const userConfig = readConfig('user');
-    const userRoot = configuredClisDirForRoot(userScopeRoot());
-    for (const [name, entry] of Object.entries(userConfig.configuredClis)) {
-        if (seen.has(name))
-            continue;
-        out.push({
-            name,
-            endpoint: entry.endpoint,
-            authEnvVar: entry.authEnvVar,
-            scope: 'user',
-            root: userRoot,
-        });
-        seen.add(name);
-    }
-    return out;
-}
-/** Get deduplicated effective registrations (one per unique name, project wins over user). */
-export function effectiveConfiguredClis() {
-    return listConfiguredCliRegistrations();
-}
-/** Resolve a configured CLI registration by name. If scope is omitted, returns the
- *  effective winner (project > user). If scope is explicit, returns the registration
- *  in that scope or null if not found. */
-export function resolveConfiguredCli(name, scope) {
-    const all = listConfiguredCliRegistrations();
-    if (scope === undefined) {
-        // Return effective winner (first in list after precedence ordering)
-        return all.find((r) => r.name === name) ?? null;
-    }
-    if (scope !== 'project' && scope !== 'user') {
-        return null; // builtin scope is not applicable
-    }
-    if (scope === 'project') {
-        // Walk every visible project root (nearest-first), matching the same
-        // precedence `listConfiguredCliRegistrations` uses — an explicit
-        // `--scope project` must find a registration in a farther project root,
-        // not only the nearest one.
-        for (const scopeRootDir of projectScopeRoots()) {
-            const config = readConfigAtRoot(scopeRootDir);
-            const entry = config.configuredClis[name];
-            if (!entry)
-                continue;
-            return {
-                name,
-                endpoint: entry.endpoint,
-                authEnvVar: entry.authEnvVar,
-                scope: 'project',
-                root: configuredClisDirForRoot(scopeRootDir),
-            };
-        }
-        return null;
-    }
-    // user scope: single root.
-    const config = readConfig('user');
-    const entry = config.configuredClis[name];
-    if (!entry)
-        return null;
-    const root = configuredClisDir('user');
-    if (!root)
-        return null;
-    return {
-        name,
-        endpoint: entry.endpoint,
-        authEnvVar: entry.authEnvVar,
-        scope: 'user',
-        root,
-    };
-}
-/** Get the cache directory for a configured CLI registration. */
-export function configuredCliCacheDir(registration) {
-    return join(registration.root, registration.name);
-}
-/** Get the manifest file path for a configured CLI. */
-export function configuredCliManifestPath(registration) {
-    return join(configuredCliCacheDir(registration), 'manifest.json');
-}
-/** Get the cache metadata file path for a configured CLI. */
-export function configuredCliCacheMetaPath(registration) {
-    return join(configuredCliCacheDir(registration), 'meta.json');
-}