@knowttl/falcon-axi 0.0.0-stage → 1.0.0-rc.2

package/.typescript-build/src/core.js

@@ -0,0 +1,31 @@
+export class CliError extends Error {
+    code;
+    help;
+    details;
+    constructor(code, message, help = [], details = {}) {
+        super(message);
+        this.code = code;
+        this.help = help;
+        this.details = details;
+    }
+    get exitCode() {
+        return ["VALIDATION_ERROR", "FQL_INVALID", "CONFIG_INVALID"].includes(this.code)
+            ? 2
+            : 1;
+    }
+}
+export function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+// Preserve numeric lexemes outside Number's exact integer domain before rounding.
+export function parseResponse(text) {
+    return JSON.parse(text, (_key, value, context) => {
+        if (typeof value !== "number" ||
+            Math.abs(value) <= Number.MAX_SAFE_INTEGER ||
+            !context?.source)
+            return value;
+        return /^-?\d+$/.test(context.source)
+            ? BigInt(context.source)
+            : context.source;
+    });
+}

package/.typescript-build/src/cql.js

@@ -0,0 +1,159 @@
+import { CliError } from "./core.js";
+// Refuse certain structural errors; ambiguous CQL remains Falcon's decision.
+export function validateQuery(query) {
+    const open = {
+        "(": ")",
+        "[": "]",
+        "{": "}",
+    };
+    const classes = {
+        "(": "parenthesis",
+        ")": "parenthesis",
+        "[": "square bracket",
+        "]": "square bracket",
+        "{": "brace",
+        "}": "brace",
+    };
+    const fail = (offset, message, expected = null) => {
+        const before = Array.from(query.slice(0, offset));
+        const line = before.filter((char) => char === "\n").length + 1;
+        const column = before.length - before.lastIndexOf("\n");
+        throw new CliError("VALIDATION_ERROR", `CQL syntax error at line ${line}, column ${column}: ${message}`, [
+            expected
+                ? `Expected ${expected}; correct the CQL structure before retrying`
+                : "Remove the unexpected closing delimiter",
+        ], { diagnostics: [{ line, column, message, expected }] });
+    };
+    if (!query.trim())
+        fail(0, "missing query", "a non-empty CQL query in --query");
+    const stack = [];
+    let content = false;
+    let pipe;
+    let assignment;
+    let previous = "";
+    let i = 0;
+    while (i < query.length) {
+        const char = query[i];
+        if (/\s/.test(char)) {
+            i++;
+            continue;
+        }
+        if (query.startsWith("/*", i)) {
+            const end = query.indexOf("*/", i + 2);
+            if (end < 0)
+                fail(i, "unterminated block comment", "*/");
+            i = end + 2;
+            continue;
+        }
+        if (query.startsWith("//", i)) {
+            const end = query.indexOf("\n", i);
+            i = end < 0 ? query.length : end;
+            continue;
+        }
+        if (assignment !== undefined) {
+            if ("|)]};,".includes(char))
+                fail(assignment, "dangling assignment", "an expression after ':='");
+            assignment = undefined;
+        }
+        const regex = char === "/";
+        if (regex &&
+            ![
+                "",
+                "=",
+                "(",
+                ",",
+                "|",
+                "[",
+                "{",
+                ";",
+                "=>",
+                "AND",
+                "OR",
+                "NOT",
+            ].includes(previous))
+            return;
+        if (char === '"' || regex) {
+            let end = i + 1;
+            while (end < query.length && query[end] !== char) {
+                if (/[\r\n]/.test(query[end]))
+                    break;
+                end +=
+                    query[end] === "\\" &&
+                        end + 1 < query.length &&
+                        !/[\r\n]/.test(query[end + 1])
+                        ? 2
+                        : 1;
+            }
+            if (end >= query.length || query[end] !== char)
+                fail(i, regex ? "unterminated regex literal" : "unterminated string", char);
+            i = end + 1;
+            while (regex && i < query.length && "dim".includes(query[i]))
+                i++;
+            content = true;
+            previous = "value";
+            continue;
+        }
+        if (Object.hasOwn(open, char)) {
+            stack.push({ char, offset: i, pipe });
+            content = false;
+            pipe = undefined;
+            previous = char;
+            i++;
+            continue;
+        }
+        else if (")]}".includes(char)) {
+            if (!stack.length || open[stack.at(-1).char] !== char)
+                fail(i, `unexpected closing ${classes[char]}`, stack.length ? open[stack.at(-1).char] : null);
+            if (!content && pipe !== undefined)
+                fail(pipe, "query ends with an empty pipeline stage", "a function after the last '|'");
+            pipe = stack.pop().pipe;
+        }
+        else if (char === "|") {
+            if (!content)
+                fail(i, "empty pipeline stage", "a filter or function before '|'");
+            content = false;
+            pipe = i;
+            previous = char;
+            i++;
+            continue;
+        }
+        else if (";,".includes(char) || query.startsWith("=>", i)) {
+            if (!content && pipe !== undefined)
+                fail(pipe, "query ends with an empty pipeline stage", "a function after the last '|'");
+            content = false;
+            pipe = undefined;
+            previous = query.startsWith("=>", i) ? "=>" : char;
+            i += previous.length;
+            continue;
+        }
+        else if (query.startsWith(":=", i)) {
+            assignment = i;
+            previous = "=";
+            i += 2;
+            continue;
+        }
+        else if (!"=!<>/".includes(char)) {
+            let end = i + 1;
+            while (end < query.length && !/\s|[()[\]{}"=,!<>;|]/.test(query[end])) {
+                if (query.startsWith(":=", end))
+                    break;
+                end++;
+            }
+            previous = query.slice(i, end);
+            content = true;
+            i = end;
+            continue;
+        }
+        content = true;
+        previous = char;
+        i++;
+    }
+    if (assignment !== undefined)
+        fail(assignment, "dangling assignment", "an expression after ':='");
+    if (stack.length) {
+        const last = stack.at(-1);
+        fail(last.offset, `unclosed ${classes[last.char]}`, open[last.char]);
+    }
+    if (!content && pipe !== undefined)
+        fail(pipe, "query ends with an empty pipeline stage", "a function after the last '|'");
+}

package/.typescript-build/src/credentials.js

@@ -0,0 +1,235 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, win32 } from "node:path";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import schema from "./axi-credential.schema.json" with { type: "json" };
+import { CliError, object } from "./core.js";
+import { registerSecret, registerMemberCid } from "./render.js";
+import { verifyWindowsFile } from "./windows-acl.js";
+import { rtrPolicy } from "./rtr-policy.js";
+const aliases = {
+    FALCON_CLIENT_ID: "FALCON_AXI_CLIENT_ID",
+    FALCON_CLIENT_SECRET: "FALCON_AXI_CLIENT_SECRET",
+    FALCON_MEMBER_CID: "FALCON_AXI_MEMBER_CID",
+    FALCON_BASE_URL: "FALCON_AXI_REGION",
+    FALCON_PROXY_URL: "FALCON_AXI_PROXY_URL",
+};
+const sourceAliases = new Map();
+export function normalizeEnvironment() {
+    const warnings = [];
+    for (const [old, current] of Object.entries(aliases)) {
+        if (process.env[old] !== undefined) {
+            warnings.push(`${old} is deprecated; use ${current}`);
+            if (process.env[current] === undefined) {
+                sourceAliases.set(current, old);
+                process.env[current] = process.env[old];
+            }
+        }
+    }
+    return warnings;
+}
+export function directory(kind) {
+    const env = process.env;
+    if (process.platform === "win32")
+        return join(env[kind === "config" ? "APPDATA" : "LOCALAPPDATA"] ||
+            join(homedir(), "AppData", kind === "config" ? "Roaming" : "Local"), "falcon-axi");
+    const root = env[`XDG_${kind.toUpperCase()}_HOME`];
+    return join(root && isAbsolute(root)
+        ? root
+        : join(homedir(), kind === "config" ? ".config" : ".local/state"), "falcon-axi");
+}
+export function configPath(flag) {
+    return (flag ||
+        process.env.FALCON_AXI_CONFIG ||
+        join(directory("config"), "config.json"));
+}
+export function writeLogPath() {
+    return (process.env.FALCON_AXI_WRITE_LOG || join(directory("state"), "writes.log"));
+}
+async function checkLegacy(path) {
+    const exists = async (candidate) => {
+        try {
+            await lstat(candidate);
+            return true;
+        }
+        catch (error) {
+            if (object(error) && error.code === "ENOENT")
+                return false;
+            throw new CliError("CONFIG_INSECURE", `cannot inspect ${candidate}`);
+        }
+    };
+    const legacy = join(homedir(), ".config/falcon-axi/credentials");
+    if (!(await exists(path)) && (await exists(legacy)))
+        throw new CliError("CONFIG_MOVED", `legacy credentials at ${legacy} must be converted to ${path}`, [
+            "Use version 1 config.json profiles with clientId and clientSecret: {env: NAME} or {file: /absolute/path}",
+            "See https://github.com/knowttl/artium-axi/blob/main/docs/credential-standard.md",
+        ]);
+}
+export async function loadProfiles(config, diagnostic = false) {
+    const path = configPath(config);
+    await checkLegacy(path);
+    const contents = await readPrivate(path, false, diagnostic);
+    if (contents === undefined)
+        return { profiles: {} };
+    let document;
+    try {
+        document = JSON.parse(contents);
+    }
+    catch {
+        throw new CliError("CONFIG_INVALID", `invalid JSON in ${path}`);
+    }
+    if (!object(document) ||
+        document.version !== 1 ||
+        !object(document.profiles) ||
+        Object.keys(document).some((key) => !["version", "defaultProfile", "profiles"].includes(key)))
+        throw new CliError("CONFIG_INVALID", "config.json requires version 1 and a profiles object");
+    const validate = new Ajv2020({ strict: false }).compile(schema);
+    for (const [name, entry] of Object.entries(document.profiles)) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name))
+            throw new CliError("CONFIG_INVALID", "invalid profile name");
+        if (!validate(entry) || !object(entry))
+            throw new CliError("CONFIG_INVALID", `profile ${name} does not match the profile schema`);
+        rtrPolicy(entry.rtr);
+        for (const field of ["clientId", "region", "memberCid"])
+            if (typeof entry[field] === "string" && !entry[field].trim())
+                throw new CliError("CONFIG_INVALID", `profile ${name} requires a nonempty string for ${field}`);
+        if (object(entry.clientSecret) &&
+            typeof entry.clientSecret.file === "string") {
+            const file = entry.clientSecret.file;
+            if (process.platform === "win32"
+                ? !/^[A-Za-z]:$/.test(win32.parse(file).root.slice(0, 2)) ||
+                    !win32.isAbsolute(file)
+                : !isAbsolute(file))
+                throw new CliError("CONFIG_INVALID", "clientSecret must reference an absolute local file");
+        }
+    }
+    const defaultProfile = document.defaultProfile;
+    if (defaultProfile !== undefined &&
+        defaultProfile !== null &&
+        (typeof defaultProfile !== "string" ||
+            !Object.hasOwn(document.profiles, defaultProfile)))
+        throw new CliError("CONFIG_INVALID", "defaultProfile must name an existing profile");
+    return {
+        profiles: document.profiles,
+        ...(typeof defaultProfile === "string" ? { defaultProfile } : {}),
+    };
+}
+export async function readPrivate(path, secret = false, diagnostic = false) {
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch (error) {
+        if (object(error) && error.code === "ENOENT")
+            return undefined;
+        throw new CliError("CONFIG_INSECURE", "cannot inspect the selected credential file");
+    }
+    if (!info.isFile() ||
+        info.isSymbolicLink() ||
+        (process.platform === "win32" &&
+            !(await verifyWindowsFile(path, diagnostic))) ||
+        (process.platform !== "win32" &&
+            (info.uid !== process.getuid() ||
+                (info.mode & (secret ? 0o077 : 0o022)) !== 0)))
+        throw new CliError("CONFIG_INSECURE", "the selected credential file is not protected");
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY |
+            (constants.O_NOFOLLOW ?? 0) |
+            (constants.O_NONBLOCK ?? 0));
+    }
+    catch {
+        throw new CliError("CONFIG_INVALID", `cannot read UTF-8 from ${path}`);
+    }
+    try {
+        const opened = await file.stat();
+        if (!opened.isFile() || opened.dev !== info.dev || opened.ino !== info.ino)
+            throw new CliError("CONFIG_INSECURE", "the credential file changed during its read check");
+        try {
+            return new TextDecoder("utf-8", { fatal: true }).decode(await file.readFile());
+        }
+        catch {
+            throw new CliError("CONFIG_INVALID", `cannot read UTF-8 from ${path}`);
+        }
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function resolveCredential(config, profile, diagnostic = false) {
+    const env = process.env;
+    const selected = profile ?? env.FALCON_AXI_PROFILE;
+    const path = configPath(config);
+    await checkLegacy(path);
+    let credential;
+    if (selected === undefined &&
+        (env.FALCON_AXI_CLIENT_ID || env.FALCON_AXI_CLIENT_SECRET)) {
+        if (!env.FALCON_AXI_CLIENT_ID || !env.FALCON_AXI_CLIENT_SECRET)
+            throw new CliError("CONFIG_INVALID", `env profile is incomplete; set ${env.FALCON_AXI_CLIENT_ID ? "FALCON_AXI_CLIENT_SECRET" : "FALCON_AXI_CLIENT_ID"}`);
+        credential = {
+            clientId: env.FALCON_AXI_CLIENT_ID,
+            clientSecret: env.FALCON_AXI_CLIENT_SECRET,
+            channel: "environment",
+            profile: "env",
+            secretSource: `env:${sourceAliases.get("FALCON_AXI_CLIENT_SECRET") ?? "FALCON_AXI_CLIENT_SECRET"}`,
+            ...(env.FALCON_AXI_REGION ? { region: env.FALCON_AXI_REGION } : {}),
+            ...(env.FALCON_AXI_MEMBER_CID
+                ? { memberCid: env.FALCON_AXI_MEMBER_CID }
+                : {}),
+        };
+    }
+    else {
+        const document = await loadProfiles(config, diagnostic);
+        const profiles = document.profiles;
+        const names = Object.keys(profiles);
+        const name = selected ??
+            document.defaultProfile ??
+            (names.length === 1 ? names[0] : undefined);
+        if (typeof name !== "string")
+            throw new CliError(names.length ? "PROFILE_AMBIGUOUS" : "PROFILE_REQUIRED", names.length
+                ? "select a profile with --profile or FALCON_AXI_PROFILE"
+                : "no Falcon profile configured", names.length
+                ? []
+                : [
+                    "Set FALCON_AXI_CLIENT_ID and FALCON_AXI_CLIENT_SECRET in the environment",
+                    `Or configure a profile with a clientSecret SecretRef in ${path}`,
+                    "Provision an API client with read scopes; only `search start`, `search stop`, and `identity activity` need NGSIEM:write",
+                ]);
+        if (!Object.hasOwn(profiles, name))
+            throw new CliError("PROFILE_NOT_FOUND", "selected profile does not exist", ["Run `falcon-axi profile list`"]);
+        const settings = profiles[name];
+        const ref = settings.clientSecret ?? { env: "FALCON_AXI_CLIENT_SECRET" };
+        if (!object(ref))
+            throw new CliError("CONFIG_INVALID", "invalid clientSecret SecretRef");
+        let secret;
+        if (typeof ref.env === "string")
+            secret = env[ref.env];
+        else if (typeof ref.file === "string" && isAbsolute(ref.file))
+            secret = (await readPrivate(ref.file, true, diagnostic))?.trimEnd();
+        if (!secret)
+            throw new CliError("AUTH_REQUIRED", "clientSecret SecretRef resolved to no value");
+        credential = {
+            clientId: settings.clientId,
+            clientSecret: secret,
+            channel: "file",
+            rtr: rtrPolicy(settings.rtr),
+            profile: name,
+            secretSource: typeof ref.env === "string"
+                ? `env:${sourceAliases.get(ref.env) ?? ref.env}`
+                : `file:${String(ref.file)}`,
+            ...(typeof ref.file === "string" ? { path: ref.file } : {}),
+            ...(typeof settings.region === "string"
+                ? { region: settings.region }
+                : {}),
+            ...(typeof settings.memberCid === "string"
+                ? { memberCid: settings.memberCid }
+                : {}),
+        };
+    }
+    registerSecret(credential.clientId);
+    registerSecret(credential.clientSecret);
+    if (credential.memberCid)
+        registerMemberCid(credential.memberCid);
+    return credential;
+}

package/.typescript-build/src/cursor.js

@@ -0,0 +1,65 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { CliError, object } from "./core.js";
+export class Cursor {
+    credential;
+    origin;
+    operation;
+    query;
+    model;
+    sort;
+    constructor(credential, origin, operation, query, model = "offset", sort = null) {
+        this.credential = credential;
+        this.origin = origin;
+        this.operation = operation;
+        this.query = query;
+        this.model = model;
+        this.sort = sort;
+    }
+    fingerprint(position) {
+        return createHmac("sha256", this.credential.clientSecret)
+            .update(JSON.stringify({
+            client_id: this.credential.clientId,
+            member_cid: this.credential.memberCid ?? null,
+            model: this.model,
+            operation: this.operation,
+            origin: this.origin,
+            position,
+            query: this.query ?? null,
+            sort: this.sort,
+        }))
+            .digest("hex");
+    }
+    encode(position) {
+        return Buffer.from(JSON.stringify({
+            operation: this.operation,
+            model: this.model,
+            position,
+            fingerprint: this.fingerprint(position),
+        })).toString("base64url");
+    }
+    decode(token) {
+        try {
+            const payload = JSON.parse(Buffer.from(token, "base64url").toString("utf8"));
+            if (!object(payload) ||
+                payload.operation !== this.operation ||
+                payload.model !== this.model ||
+                (this.model === "offset" ||
+                    (this.model === "offset-or-token" &&
+                        typeof payload.position === "number")
+                    ? !Number.isSafeInteger(payload.position) ||
+                        payload.position < 0
+                    : typeof payload.position !== "string" || !payload.position) ||
+                typeof payload.fingerprint !== "string" ||
+                !/^[a-f0-9]{64}$/.test(payload.fingerprint) ||
+                !timingSafeEqual(Buffer.from(payload.fingerprint), Buffer.from(this.fingerprint(payload.position))))
+                throw new Error("cursor");
+            return payload.position;
+        }
+        catch {
+            throw new CliError("VALIDATION_ERROR", "this cursor does not continue the current query", [
+                "A cursor is bound to its operation, filter, sort, region, tenant selection, and credential",
+                "Re-run the command without `--cursor` to start a fresh read",
+            ]);
+        }
+    }
+}

package/.typescript-build/src/domain.js

@@ -0,0 +1,119 @@
+import { CliError, object } from "./core.js";
+import { responseFailure } from "./auth.js";
+import { requestRead } from "./transport/https.js";
+import { malformed } from "./response.js";
+import { Cursor } from "./cursor.js";
+import { Raw } from "./render.js";
+export const text = (value) => typeof value === "string" && value ? value : undefined;
+export const quote = (value) => /^[\w@%+=:,./-]+$/.test(value)
+    ? value
+    : `'${value.replaceAll("'", `'"'"'`)}'`;
+export const project = (record, fields) => Object.fromEntries(fields.map((field) => [field, record[field] ?? "unknown"]));
+export class Domain {
+    invocation;
+    credential;
+    session;
+    allowUnknown;
+    signal;
+    suggestion;
+    constructor(invocation, credential, session, allowUnknown, signal) {
+        this.invocation = invocation;
+        this.credential = credential;
+        this.session = session;
+        this.allowUnknown = allowUnknown;
+        this.signal = signal;
+        const { command, flags, id } = invocation;
+        const values = ["identity list", "identity timeline"].includes(command.name)
+            ? ["since", "limit", "name", "email", "domain", "type", "category"]
+            : /^(exclusion|policy) /.test(command.name)
+                ? [...command.values.filter((value) => value !== "type"), "type"]
+                : command.values;
+        this.suggestion = `falcon-axi ${command.name}${id ? ` ${quote(id)}` : ""}${flags.has("--all") ? " --all" : ""}${values
+            .filter((key) => key !== "cursor" && flags.has(`--${key}`))
+            .map((key) => ` --${key} ${quote(key === "filter" && /\b(?:cid|member_cid)\s*:/i.test(flags.get(`--${key}`)) ? "<original-filter>" : flags.get(`--${key}`))}`)
+            .join("")}`;
+    }
+    async response(operation, subject, query = {}, body, missing = false) {
+        const response = await requestRead(operation, this.session.base, this.session.token, query, body, this.allowUnknown, this.signal);
+        if (response.status === 404 && !missing) {
+            const noun = this.invocation.command.name.startsWith("identity sensor ")
+                ? "identity sensor"
+                : this.invocation.command.name.split(" ")[0];
+            throw new CliError("NOT_FOUND", noun === "host-group"
+                ? "no host group matched that identifier"
+                : `no ${subject} matched that identifier`, [
+                `Run \`falcon-axi ${noun} list${noun === "policy" ? ` --type ${this.invocation.flags.get("--type")}` : ""}\`${noun === "host-group" ? "" : " to see current identifiers"}`,
+            ]);
+        }
+        if (response.status === 403 &&
+            operation === "GetVulnerabilities" &&
+            this.invocation.command.name === "cve show") {
+            try {
+                responseFailure(response, subject, false, false, operation);
+            }
+            catch (error) {
+                if (error instanceof CliError && error.code === "SCOPE_DENIED")
+                    throw new CliError(error.code, error.message, [
+                        ...error.help,
+                        "This scope requires a Falcon Intelligence subscription; Spotlight's Vulnerabilities:read does not satisfy it",
+                        "If the scope is missing from the API client picker, ask your Falcon administrator about the license",
+                    ], error.details);
+                throw error;
+            }
+        }
+        if (response.status !== 200 && !(missing && response.status === 404))
+            responseFailure(response, subject, false, false, operation);
+        return response;
+    }
+    async read(operation, subject, query = {}, body, missing = false) {
+        const response = await this.response(operation, subject, query, body, missing);
+        if (missing && response.status === 404)
+            return {
+                rows: [],
+                total: undefined,
+                pagination: {},
+                meta: {},
+            };
+        const envelope = object(response.body) ? response.body : {};
+        const rows = operation === "GetSensorUsageWeekly" && Array.isArray(response.body)
+            ? response.body
+            : envelope.resources;
+        if (!Array.isArray(rows) ||
+            (Array.isArray(envelope.errors) && envelope.errors.length))
+            malformed(response, "Falcon returned a malformed resources array");
+        const meta = object(envelope.meta) ? envelope.meta : {};
+        const pagination = object(meta.pagination) ? meta.pagination : {};
+        const total = typeof pagination.total === "number" &&
+            Number.isSafeInteger(pagination.total) &&
+            pagination.total >= 0
+            ? pagination.total
+            : undefined;
+        return { rows: rows, total, pagination, meta };
+    }
+    async hydrate(operation, subject, ids, key = "id", body = false) {
+        const records = new Map();
+        const chunk = operation === "GetSensorDetails" ? 200 : 100;
+        for (let start = 0; start < ids.length; start += chunk) {
+            const batch = ids.slice(start, start + chunk);
+            const result = await this.read(operation, subject, body ? {} : { ids: batch }, body ? { ids: batch } : undefined, ["get_accounts", "get_iot_hosts", "GetVulnerabilities"].includes(operation));
+            for (const row of result.rows)
+                if (object(row) && text(row[key]))
+                    records.set(String(row[key]), row);
+        }
+        return ids.flatMap((id) => (records.has(id) ? [records.get(id)] : []));
+    }
+    cursor(operation, filter, model = "offset", sort = null) {
+        return new Cursor(this.credential, this.session.base, operation, filter, model, sort);
+    }
+    continuation(output, context, next) {
+        if (next === undefined)
+            return;
+        const token = context.encode(next);
+        output.value.continuation_cursor = token;
+        output.help.push(`Run \`${this.suggestion}${this.invocation.flags.has("--full") ? " --full" : ""} --cursor ${token}\` for the next page`);
+    }
+}
+export const count = (rows, total) => new Raw(`${rows.length} of ${total ?? "unknown"} total`);
+export const ids = (rows) => rows.filter((row) => typeof row === "string");
+export const more = (length, offset, total, limit) => length > 0 &&
+    (total === undefined ? length >= limit : offset + length < total);

package/.typescript-build/src/executable.js

@@ -0,0 +1,45 @@
+import { realpathSync, statSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { CliError } from "./core.js";
+export function shellArgument(value) {
+    return process.platform === "win32"
+        ? `"${value}"`
+        : `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+export function executableCommand(hook = false) {
+    const entry = realpathSync(resolve(process.argv[1]));
+    const target = hook ? join(dirname(entry), "hook.js") : entry;
+    const name = hook ? "falcon-axi-hook" : "falcon-axi";
+    if (!statSync(target).isFile())
+        throw new CliError("CONFIG_INVALID", `cannot locate ${name}; reinstall falcon-axi`);
+    return [process.execPath, target];
+}
+export function durableInstallation() {
+    const entry = resolve(process.argv[1]);
+    const hook = join(dirname(realpathSync(entry)), "hook.js");
+    const temporaryRoots = process.platform === "win32" ? [] : ["/tmp", realpathSync("/tmp")];
+    for (const path of [
+        entry,
+        realpathSync(entry),
+        hook,
+        realpathSync(hook),
+        process.execPath,
+    ]) {
+        const parts = path.split(sep);
+        if (temporaryRoots.some((root) => path === root || path.startsWith(root + sep)) ||
+            parts.some((part) => [".treehouse", "worktrees", ".no-mistakes"].includes(part)))
+            throw new CliError("CONFIG_INVALID", "session hooks require a durable installation outside temporary directories and git worktrees", [
+                "Install with `npm install -g @knowttl/falcon-axi@next`, then run `falcon-axi setup hooks`",
+            ]);
+        for (let parent = dirname(path); parent !== dirname(parent); parent = dirname(parent)) {
+            try {
+                if (statSync(join(parent, ".git")).isFile())
+                    throw new CliError("CONFIG_INVALID", "session hooks require a durable installation outside temporary directories and git worktrees");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+    }
+}