@git.zone/cli 2.23.0 → 2.25.0

package/dist_ts/mod_services/classes.serviceoptions.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Committed, per-service configuration.
+ *
+ * Deliberately a SIBLING of `@git.zone/cli.services` rather than a richer
+ * `services` value. `@git.zone/tsdeploy` derives a workload's
+ * `requiredCapabilities` from that array and **throws** on any element that is
+ * not a canonical lowercase string, so an array of objects — or a mixed array —
+ * would hard-fail real deployments. `services` therefore stays exactly
+ * `string[]`, and configuration lives here where TsDeploy never looks.
+ *
+ * Config path: `@git.zone/cli.serviceOptions`.
+ */
+export declare const serviceOptionsConfigKey = "serviceOptions";
+export interface IMongodbServiceOptions {
+    /**
+     * When false, mongod runs without authentication and is published on
+     * loopback only. Opt-in, for runtimes whose `node:crypto` cannot complete a
+     * SCRAM handshake (notably Deno). Absent means enabled.
+     */
+    auth?: boolean;
+}
+export interface IServiceOptions {
+    mongodb?: IMongodbServiceOptions;
+}
+/**
+ * Read declared service options from `.smartconfig.json`.
+ *
+ * Unknown or malformed values are ignored rather than throwing: this file is
+ * hand-edited, and a typo must not make every services command unusable. The
+ * effect of ignoring is always the safe default (auth enabled).
+ */
+export declare const readServiceOptions: (cwd?: string) => Promise<IServiceOptions>;
+/**
+ * Declare whether MongoDB enforces authentication for this project.
+ *
+ * Writing `true` removes the declaration instead of recording it: the default
+ * is already "enabled", and an absent key keeps committed config free of noise
+ * while remaining unambiguous to an older CLI that ignores this key entirely.
+ */
+export declare const writeMongodbAuthOption: (authEnabledArg: boolean, cwd?: string) => Promise<void>;
+/**
+ * Where an effective setting came from, so the CLI can say so out loud.
+ */
+export type TServiceOptionSource = 'declared' | 'local' | 'default';
+export interface IResolvedMongoAuth {
+    authEnabled: boolean;
+    source: TServiceOptionSource;
+}
+/**
+ * Resolve the effective MongoDB auth mode.
+ *
+ * A committed declaration wins over `.nogit/env.json`. That ordering is what
+ * makes a fresh checkout reproducible: without it, a stale local env.json would
+ * silently diverge from what the repository declares. When nothing is declared,
+ * an existing local value is preserved so projects configured before
+ * `serviceOptions` existed keep working.
+ */
+export declare const resolveMongoAuth: (declaredOptionsArg: IServiceOptions, localValueArg: boolean | undefined) => IResolvedMongoAuth;

package/dist_ts/mod_services/classes.serviceoptions.js

@@ -0,0 +1,93 @@
+import * as plugins from './mod.plugins.js';
+import { getCliConfigValueFromData, readSmartconfigFile, setCliConfigValueInData, writeSmartconfigFile, } from '../helpers.smartconfig.js';
+/**
+ * Committed, per-service configuration.
+ *
+ * Deliberately a SIBLING of `@git.zone/cli.services` rather than a richer
+ * `services` value. `@git.zone/tsdeploy` derives a workload's
+ * `requiredCapabilities` from that array and **throws** on any element that is
+ * not a canonical lowercase string, so an array of objects — or a mixed array —
+ * would hard-fail real deployments. `services` therefore stays exactly
+ * `string[]`, and configuration lives here where TsDeploy never looks.
+ *
+ * Config path: `@git.zone/cli.serviceOptions`.
+ */
+export const serviceOptionsConfigKey = 'serviceOptions';
+const isPlainObject = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+/**
+ * Read declared service options from `.smartconfig.json`.
+ *
+ * Unknown or malformed values are ignored rather than throwing: this file is
+ * hand-edited, and a typo must not make every services command unusable. The
+ * effect of ignoring is always the safe default (auth enabled).
+ */
+export const readServiceOptions = async (cwd = process.cwd()) => {
+    const smartconfigData = await readSmartconfigFile(cwd);
+    const rawOptions = getCliConfigValueFromData(smartconfigData, serviceOptionsConfigKey);
+    if (!isPlainObject(rawOptions)) {
+        return {};
+    }
+    const options = {};
+    if (isPlainObject(rawOptions.mongodb) && typeof rawOptions.mongodb.auth === 'boolean') {
+        options.mongodb = { auth: rawOptions.mongodb.auth };
+    }
+    return options;
+};
+/**
+ * Declare whether MongoDB enforces authentication for this project.
+ *
+ * Writing `true` removes the declaration instead of recording it: the default
+ * is already "enabled", and an absent key keeps committed config free of noise
+ * while remaining unambiguous to an older CLI that ignores this key entirely.
+ */
+export const writeMongodbAuthOption = async (authEnabledArg, cwd = process.cwd()) => {
+    const smartconfigData = await readSmartconfigFile(cwd);
+    const rawOptions = getCliConfigValueFromData(smartconfigData, serviceOptionsConfigKey);
+    const nextOptions = isPlainObject(rawOptions) ? { ...rawOptions } : {};
+    if (authEnabledArg) {
+        if (isPlainObject(nextOptions.mongodb)) {
+            const { auth, ...restOfMongodb } = nextOptions.mongodb;
+            if (Object.keys(restOfMongodb).length > 0) {
+                nextOptions.mongodb = restOfMongodb;
+            }
+            else {
+                delete nextOptions.mongodb;
+            }
+        }
+    }
+    else {
+        nextOptions.mongodb = { ...(isPlainObject(nextOptions.mongodb) ? nextOptions.mongodb : {}), auth: false };
+    }
+    if (Object.keys(nextOptions).length === 0) {
+        // Drop the key entirely rather than leaving an empty object behind.
+        const cliConfig = smartconfigData['@git.zone/cli'];
+        if (isPlainObject(cliConfig)) {
+            delete cliConfig[serviceOptionsConfigKey];
+        }
+    }
+    else {
+        setCliConfigValueInData(smartconfigData, serviceOptionsConfigKey, nextOptions);
+    }
+    await writeSmartconfigFile(smartconfigData, cwd);
+};
+/**
+ * Resolve the effective MongoDB auth mode.
+ *
+ * A committed declaration wins over `.nogit/env.json`. That ordering is what
+ * makes a fresh checkout reproducible: without it, a stale local env.json would
+ * silently diverge from what the repository declares. When nothing is declared,
+ * an existing local value is preserved so projects configured before
+ * `serviceOptions` existed keep working.
+ */
+export const resolveMongoAuth = (declaredOptionsArg, localValueArg) => {
+    if (typeof declaredOptionsArg.mongodb?.auth === 'boolean') {
+        return { authEnabled: declaredOptionsArg.mongodb.auth, source: 'declared' };
+    }
+    if (typeof localValueArg === 'boolean') {
+        return { authEnabled: localValueArg, source: 'local' };
+    }
+    return { authEnabled: true, source: 'default' };
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5zZXJ2aWNlb3B0aW9ucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL21vZF9zZXJ2aWNlcy9jbGFzc2VzLnNlcnZpY2VvcHRpb25zLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sa0JBQWtCLENBQUM7QUFDNUMsT0FBTyxFQUNMLHlCQUF5QixFQUN6QixtQkFBbUIsRUFDbkIsdUJBQXVCLEVBQ3ZCLG9CQUFvQixHQUNyQixNQUFNLDJCQUEyQixDQUFDO0FBR25DOzs7Ozs7Ozs7OztHQVdHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sdUJBQXVCLEdBQUcsZ0JBQWdCLENBQUM7QUFleEQsTUFBTSxhQUFhLEdBQUcsQ0FBQyxLQUFjLEVBQWdDLEVBQUU7SUFDckUsT0FBTyxPQUFPLEtBQUssS0FBSyxRQUFRLElBQUksS0FBSyxLQUFLLElBQUksSUFBSSxDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsS0FBSyxDQUFDLENBQUM7QUFDOUUsQ0FBQyxDQUFDO0FBRUY7Ozs7OztHQU1HO0FBQ0gsTUFBTSxDQUFDLE1BQU0sa0JBQWtCLEdBQUcsS0FBSyxFQUNyQyxNQUFjLE9BQU8sQ0FBQyxHQUFHLEVBQUUsRUFDRCxFQUFFO0lBQzVCLE1BQU0sZUFBZSxHQUFHLE1BQU0sbUJBQW1CLENBQUMsR0FBRyxDQUFDLENBQUM7SUFDdkQsTUFBTSxVQUFVLEdBQUcseUJBQXlCLENBQUMsZUFBZSxFQUFFLHVCQUF1QixDQUFDLENBQUM7SUFDdkYsSUFBSSxDQUFDLGFBQWEsQ0FBQyxVQUFVLENBQUMsRUFBRSxDQUFDO1FBQy9CLE9BQU8sRUFBRSxDQUFDO0lBQ1osQ0FBQztJQUVELE1BQU0sT0FBTyxHQUFvQixFQUFFLENBQUM7SUFDcEMsSUFBSSxhQUFhLENBQUMsVUFBVSxDQUFDLE9BQU8sQ0FBQyxJQUFJLE9BQU8sVUFBVSxDQUFDLE9BQU8sQ0FBQyxJQUFJLEtBQUssU0FBUyxFQUFFLENBQUM7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

package/dist_ts/mod_services/classes.servicepruner.d.ts

@@ -0,0 +1,102 @@
+import { type TServiceName } from './classes.servicedatamarker.js';
+/** Default inactivity threshold before a project is even considered stale. */
+export declare const defaultStaleDays = 30;
+/**
+ * How a project was classified.
+ *
+ * - `live`     — recent activity; never a reclamation candidate.
+ * - `stale`    — project still on disk but inactive past the threshold.
+ * - `orphaned` — project directory no longer exists.
+ * - `unknown`  — insufficient evidence to classify; never reclaimed.
+ */
+export type TServiceProjectState = 'live' | 'stale' | 'orphaned' | 'unknown';
+/** Why a candidate was left alone. */
+export interface IServiceSkipReason {
+    target: string;
+    reason: string;
+}
+export interface IServiceDataDirReport {
+    service: TServiceName;
+    path: string;
+    exists: boolean;
+    sizeBytes: number;
+    reclaimable: boolean;
+    reason: string;
+}
+export interface IServiceContainerReport {
+    id: string;
+    name: string;
+    state: string;
+    running: boolean;
+    reclaimable: boolean;
+    reason: string;
+}
+export interface IServiceProjectReport {
+    projectPath: string;
+    projectName: string;
+    state: TServiceProjectState;
+    stateReason: string;
+    lastActive: number | null;
+    inactiveDays: number | null;
+    projectDirExists: boolean;
+    registered: boolean;
+    markerPresent: boolean;
+    containers: IServiceContainerReport[];
+    dataDirectories: IServiceDataDirReport[];
+    totalDataBytes: number;
+    reclaimableDataBytes: number;
+}
+export interface IServicePrunePlan {
+    staleDays: number;
+    dockerAvailable: boolean;
+    projects: IServiceProjectReport[];
+    registryEntriesToRemove: string[];
+    containersToRemove: Array<{
+        id: string;
+        name: string;
+        projectPath: string;
+    }>;
+    dataDirsToRemove: Array<{
+        projectPath: string;
+        service: TServiceName;
+        path: string;
+        sizeBytes: number;
+    }>;
+    skipped: IServiceSkipReason[];
+    totals: {
+        projects: number;
+        totalDataBytes: number;
+        reclaimableDataBytes: number;
+        /** Bytes that would be reclaimable if the holding containers were stopped first. */
+        blockedByRunningBytes: number;
+    };
+}
+export interface IServicePrunerOptions {
+    staleDays?: number;
+}
+/**
+ * Plans and applies reclamation of resources created by `gitzone services`.
+ *
+ * Design mirrors `@git.zone/tsdocker`'s `TsDockerPruner`: build an explicit
+ * plan, print it, and only mutate on an explicit apply that re-verifies every
+ * single item. Nothing is ever matched by image or by bare name pattern, and
+ * every ambiguity resolves to "skip".
+ */
+export declare class ServicePruner {
+    private docker;
+    private globalRegistry;
+    private staleDays;
+    constructor(optionsArg?: IServicePrunerOptions);
+    /**
+     * Build a reclamation plan. Read-only: touches nothing.
+     */
+    createPlan(): Promise<IServicePrunePlan>;
+    /**
+     * Apply a plan, re-verifying every item immediately before it is removed.
+     *
+     * Any drift between plan and current reality aborts with an error rather than
+     * removing something that may since have become live.
+     */
+    applyPlan(planArg: IServicePrunePlan): Promise<void>;
+    private isClaimedByExactlyOneProject;
+}