@harperfast/harper 5.2.0 → 5.2.2

package/dist/bin/harper.js

@@ -38,11 +38,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatCliError = formatCliError;
+exports.wantsTopLevelHelp = wantsTopLevelHelp;
 exports.harper = harper;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const harper_logger_ts_1 = __importDefault(require("../utility/logging/harper_logger.js"));
 const cliOperations = __importStar(require("./cliOperations.js"));
+const help_ts_1 = require("./help.js");
 const packageUtils_js_1 = require("../utility/packageUtils.js");
 const checkNodeVersion_js_1 = __importDefault(require("../launchServiceScripts/utility/checkNodeVersion.js"));
 const hdbTerms = __importStar(require("../utility/hdbTerms.js"));
@@ -50,54 +52,6 @@ const { SERVICE_ACTIONS_ENUM, OPERATIONS_ENUM } = hdbTerms;
 if (typeof process.setSourceMapsEnabled === 'function') {
     process.setSourceMapsEnabled(true); // this is necessary for source maps to work, at least on the main thread.
 }
-const HELP = `
-Usage: harperdb [command]
-
-With no command, harper will simply run Harper (in the foreground)
-
-Documentation: https://docs.harperdb.io/
-
-By default, the CLI also supports certain Operation APIs. Specify the operation name and any required parameters, and omit the 'operation' command.
-
-Commands:
-agent [message]                 - Chat with the built-in agent (interactive, or one-shot with a message; alias: chat)
-copy-db <source> <target>       - Copies a database from source path to target path
-dev <path>                      - Run the application in dev mode with debugging, foreground logging, no auth
-install                         - Install harperdb
-<api-operation> <param>=<value> - Run an API operation and return result to the CLI, not all operations are supported
-                                   To authenticate as a different user than the one being operated on
-                                   (e.g. add_user/alter_user), set HARPER_CLI_USERNAME/HARPER_CLI_PASSWORD
-                                   or run 'harper login'. The equivalent auth_username=<value>
-                                   auth_password=<value> args also work, but a password passed as an
-                                   argument is exposed in shell history, process listings and CI logs.
-                                   A saved login token always outranks username=/password=, so a
-                                   stale token that fails to refresh will 401 rather than falling
-                                   back to them — run 'harper logout' or pass auth_username=/
-                                   auth_password= to override it.
-login [target] [username]       - Login to a remote or local Harper instance
-                                   --for-ci prints the CI/CD credentials (target + long-lived
-                                   refresh token) to stdout in dotenv format, and everything else
-                                   to stderr, so it pipes without the token hitting your screen:
-                                     harper login --for-ci | gh secret set --env-file -
-                                   Log in as a user dedicated to that one CI consumer: Harper
-                                   stores a single refresh token per user, so this revokes any
-                                   refresh token that user already holds — another runner, another
-                                   machine, or an earlier 'harper login' will 401 on its next
-                                   refresh. Two consumers cannot share a user.
-logout [target]                 - Logout from Harper and clear saved JWT
-mcp [subcommand]                - MCP stdio bridge / print-config / doctor (see 'harper mcp help')
-register                        - Register harperdb
-renew-certs                     - Generate a new set of self-signed certificates
-restart                         - Restart the harperdb background process
-run <path>                      - Run the application in the specified path
-start                           - Starts a separate background process for harperdb and CLI will exit
-status                          - Print the status of Harper
-stop                            - Stop the harperdb background process
-help                            - Display this output
-upgrade                         - Upgrade harperdb
-version                         - Print the version
-deploy                          - Deploy the application locally or remotely with target=<remote url>
-`;
 /**
  * Format a CLI error for the terminal. Expected, user-facing errors (a `ClientError` from an
  * operation — bad args, not found, a locked backup repo — which carry a numeric `statusCode`) get
@@ -110,6 +64,17 @@ function formatCliError(error) {
         return `${message}\n${error.stack}`;
     return message;
 }
+/**
+ * Whether a `-h`/`--help` anywhere in `argv` should print the top-level help. Returns false for the
+ * subcommands that own their own `--help` — mcp and agent/chat parse `process.argv.slice(3)`
+ * themselves downstream — so `harper mcp --help` reaches the mcp handler instead of this help.
+ */
+function wantsTopLevelHelp(argv, service) {
+    const delegatesHelp = service === SERVICE_ACTIONS_ENUM.MCP ||
+        service === SERVICE_ACTIONS_ENUM.AGENT ||
+        service === SERVICE_ACTIONS_ENUM.CHAT;
+    return !delegatesHelp && (argv.includes('-h') || argv.includes('--help'));
+}
 async function harper() {
     let nodeResults = (0, checkNodeVersion_js_1.default)();
     if (nodeResults) {
@@ -124,12 +89,15 @@ async function harper() {
         }
     }
     let service;
-    if (process.argv && process.argv[2] && !process.argv[2].startsWith('-')) {
+    if (process.argv?.[2] && !process.argv[2].startsWith('-')) {
         service = process.argv[2].toLowerCase();
     }
+    if (wantsTopLevelHelp(process.argv, service)) {
+        return (0, help_ts_1.help)();
+    }
     switch (service) {
         case SERVICE_ACTIONS_ENUM.HELP:
-            return HELP;
+            return (0, help_ts_1.help)();
         case SERVICE_ACTIONS_ENUM.START:
             return require('./run').launch();
         case SERVICE_ACTIONS_ENUM.INSTALL:

package/dist/bin/harper.js.map

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

package/dist/bin/help.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `harper help` / `harper -h` output, kept as structured data so {@link help} can render it to
+ * the current terminal width (capped at 120 columns) at call time. Content lives separately from
+ * layout: editing the text can't break the wrapping, command names stay column-aligned across
+ * sections, and the CI/CD sample stays a verbatim, copy-pasteable line at any width.
+ */
+/** Render the CLI help, wrapped to the terminal width (capped at 120, and 120 when not a TTY). */
+export declare function help(): string;

package/dist/bin/help.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * The `harper help` / `harper -h` output, kept as structured data so {@link help} can render it to
+ * the current terminal width (capped at 120 columns) at call time. Content lives separately from
+ * layout: editing the text can't break the wrapping, command names stay column-aligned across
+ * sections, and the CI/CD sample stays a verbatim, copy-pasteable line at any width.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.help = help;
+const MAX_WIDTH = 120;
+const INDENT = 2; // leading spaces for command names and detail blocks
+const DASH = ' - '; // separator between a command name and its description
+// Minimum description width for the two-column command layout. On terminals too narrow for it
+// (width < descCol + this), command rows stack the name above an indented description instead of
+// overflowing. Set to the widest word in any command description so two-column never overflows.
+const MIN_DESC_WIDTH = 20;
+const SECTIONS = [
+    { blocks: [{ text: 'Usage: harperdb [command]' }] },
+    { blocks: [{ text: 'With no command, harper will simply run Harper (in the foreground)' }] },
+    { blocks: [{ text: 'Documentation: https://docs.harperdb.io/' }] },
+    {
+        blocks: [
+            {
+                text: [
+                    'By default, the CLI also supports certain Operation APIs. Specify the operation name and any required',
+                    "parameters, and omit the 'operation' command.",
+                ].join(' '),
+            },
+        ],
+    },
+    { blocks: [{ text: 'Commands:' }] },
+    {
+        heading: 'Server',
+        blocks: [
+            {
+                commands: [
+                    ['start', 'Starts a separate background process for harperdb and CLI will exit'],
+                    ['stop', 'Stop the harperdb background process'],
+                    ['restart', 'Restart the harperdb background process'],
+                    ['status', 'Print the status of Harper'],
+                ],
+            },
+        ],
+    },
+    {
+        heading: 'Applications',
+        blocks: [
+            {
+                commands: [
+                    ['run <path>', 'Run the application in the specified path'],
+                    ['dev <path>', 'Run the application in dev mode with debugging, foreground logging, no auth'],
+                    ['deploy', 'Deploy the application locally or remotely with target=<remote url>'],
+                ],
+            },
+        ],
+    },
+    {
+        heading: 'Install & maintenance',
+        blocks: [
+            {
+                commands: [
+                    ['install', 'Install harperdb'],
+                    ['upgrade', 'Upgrade harperdb'],
+                    ['register', 'Register harperdb'],
+                    ['renew-certs', 'Generate a new set of self-signed certificates'],
+                    ['copy-db <source> <target>', 'Copies a database from source path to target path'],
+                    ['version', 'Print the version'],
+                    ['help', 'Display this output'],
+                ],
+            },
+        ],
+    },
+    {
+        heading: 'Accounts',
+        blocks: [
+            { pre: 'login [target] [username]', indent: INDENT },
+            {
+                text: [
+                    'Login to a remote or local Harper instance. --for-ci prints the CI/CD credentials (target +',
+                    'long-lived refresh token) to stdout in dotenv format, and everything else to stderr, so it pipes',
+                    'without the token hitting your screen:',
+                ].join(' '),
+                indent: 4,
+            },
+            { pre: 'harper login --for-ci | gh secret set --env-file -', indent: 6 },
+            {
+                text: [
+                    'Log in as a user dedicated to that one CI consumer: Harper stores a single refresh token per user, so',
+                    'this revokes any refresh token that user already holds — another runner, another machine, or an earlier',
+                    "'harper login' will 401 on its next refresh. Two consumers cannot share a user.",
+                ].join(' '),
+                indent: 4,
+            },
+            { commands: [['logout [target]', 'Logout from Harper and clear saved JWT']] },
+        ],
+    },
+    {
+        heading: 'Assistants',
+        blocks: [
+            {
+                commands: [
+                    ['agent [message]', 'Chat with the built-in agent (interactive, or one-shot with a message; alias: chat)'],
+                    ['mcp [subcommand]', "MCP stdio bridge / print-config / doctor (see 'harper mcp help')"],
+                ],
+            },
+        ],
+    },
+    {
+        heading: 'Operations API',
+        blocks: [
+            { pre: '<api-operation> <param>=<value>', indent: INDENT },
+            {
+                text: [
+                    'Run an API operation and return the result to the CLI (not all operations are supported). See the full',
+                    'list of operations at: https://docs.harperdb.io/reference/v5/operations-api/operations',
+                ].join(' '),
+                indent: 4,
+            },
+            {
+                text: [
+                    'To authenticate as a different user than the one being operated on (e.g. add_user/alter_user), set',
+                    "HARPER_CLI_USERNAME/HARPER_CLI_PASSWORD or run 'harper login'. The equivalent auth_username=<value>",
+                    'auth_password=<value> args also work, but a password passed as an argument is exposed in shell',
+                    'history, process listings and CI logs. A saved login token always outranks username=/password=, so a',
+                    "stale token that fails to refresh will 401 rather than falling back to them — run 'harper logout' or",
+                    'pass auth_username=/auth_password= to override it.',
+                ].join(' '),
+                indent: 4,
+            },
+        ],
+    },
+];
+const pad = (count) => ' '.repeat(count);
+/** Greedy word wrap. Never splits a token, so URLs and flags survive intact (they overflow). */
+function wrap(text, width) {
+    const words = text.split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return [];
+    const lines = [];
+    let line = words[0];
+    for (let i = 1; i < words.length; i++) {
+        if (line.length + 1 + words[i].length > width) {
+            lines.push(line);
+            line = words[i];
+        }
+        else {
+            line += ' ' + words[i];
+        }
+    }
+    lines.push(line);
+    return lines;
+}
+function renderBlock(block, width, nameWidth, descCol) {
+    if ('commands' in block) {
+        // Two columns when the terminal leaves a readable description column; otherwise stack the name
+        // above an indented description so narrow terminals don't overflow the command rows.
+        const twoColumn = width - descCol >= MIN_DESC_WIDTH;
+        return block.commands.flatMap(([name, description]) => {
+            if (twoColumn) {
+                const wrapped = wrap(description, width - descCol);
+                const head = pad(INDENT) + name.padEnd(nameWidth) + DASH;
+                return [head + (wrapped[0] ?? ''), ...wrapped.slice(1).map((line) => pad(descCol) + line)];
+            }
+            const detail = INDENT * 2;
+            return [pad(INDENT) + name, ...wrap(description, Math.max(1, width - detail)).map((line) => pad(detail) + line)];
+        });
+    }
+    if ('pre' in block)
+        return [pad(block.indent ?? 0) + block.pre];
+    const indent = block.indent ?? 0;
+    return wrap(block.text, Math.max(1, width - indent)).map((line) => pad(indent) + line);
+}
+/** Render the CLI help, wrapped to the terminal width (capped at 120, and 120 when not a TTY). */
+function help() {
+    const width = Math.min(process.stdout.columns || MAX_WIDTH, MAX_WIDTH);
+    // One shared description column across every command list so names line up between sections,
+    // driven by the longest command name.
+    const names = SECTIONS.flatMap((section) => section.blocks.flatMap((block) => ('commands' in block ? block.commands.map(([name]) => name) : [])));
+    const nameWidth = Math.max(...names.map((name) => name.length));
+    const descCol = INDENT + nameWidth + DASH.length;
+    const lines = [];
+    for (const section of SECTIONS) {
+        if (lines.length)
+            lines.push(''); // blank line between sections
+        if (section.heading)
+            lines.push(section.heading);
+        for (const block of section.blocks)
+            lines.push(...renderBlock(block, width, nameWidth, descCol));
+    }
+    return '\n' + lines.join('\n') + '\n';
+}
+//# sourceMappingURL=help.js.map

package/dist/bin/help.js.map

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

package/dist/components/Application.d.ts

@@ -58,7 +58,20 @@ interface GitReference {
  */
 export declare function parseGitReference(packageIdentifier: string): GitReference | null;
 export declare const ASIDE_STAGING_DIR = ".deploy-aside";
+type ExtractionTransaction = {
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+};
 export declare const GIT_CREDENTIAL_HELPER_PATH: string;
+type InstalledPackageMetadata = {
+    files: Map<string, Buffer>;
+    readable: boolean;
+    hasLockfile: boolean;
+    hasInstallableDependencies: boolean;
+};
+export declare function readInstalledPackageMetadata(directory: string): Promise<InstalledPackageMetadata>;
+export declare function installedPackageMetadataEqual(previous: InstalledPackageMetadata, current: InstalledPackageMetadata): boolean;
+export declare function installedRuntimeChanged(previous: InstalledPackageMetadata, current: InstalledPackageMetadata, installationIsOpaque: boolean): boolean;
 /**
  * Extract an application given payload (content of the application) or package (npm-compatible identifier to the application).
  *
@@ -69,7 +82,7 @@ export declare const GIT_CREDENTIAL_HELPER_PATH: string;
  * This method may be called from any Harper thread. Same-component calls are serialized across
  * threads by the preparation lock below.
  */
-export declare function extractApplication(application: Application): Promise<void>;
+export declare function extractApplication(application: Application, deferCommit?: boolean): Promise<ExtractionTransaction | undefined>;
 /**
  * Install an application to its relative `application.dirPath` using either a
  * configured `application.install` command, a derived package manager from the
@@ -119,6 +132,8 @@ export declare class Application {
     gitCredentials?: ResolvedGitCredential[];
     npmUserconfigPath?: string;
     isNewComponent: boolean;
+    packageMetadataChanged: boolean;
+    installationIsOpaque: boolean;
     constructor({ name, payload, packageIdentifier, install, onInstallLine, credentials }: ApplicationOptions);
     writeTransientNpmrc(): Promise<void>;
     get gitCredentialEnv(): Record<string, string> | undefined;