@floh-solutions/pharos-cli 0.4.0 → 0.13.0

package/dist/commands/hooks.js

@@ -0,0 +1,184 @@
+import { requiredSubscriptions, subscriptionStatus, } from "@floh-solutions/ado-core";
+import { emit, usageError } from "../output.js";
+import { approve } from "../session.js";
+export async function runHooks(io, session, positionals, input) {
+    const verb = positionals[0] ?? "list";
+    switch (verb) {
+        case "list":
+            return list(io, session);
+        case "check":
+            return check(io, session, input);
+        case "create":
+            return create(io, session, input);
+        case "repoint":
+            return repoint(io, session, input);
+        case "delete":
+            return remove(io, session, positionals[1]);
+        default:
+            throw usageError(`Unknown hooks verb "${verb}". Try list, check, create, repoint or delete.`);
+    }
+}
+async function list(io, session) {
+    const subscriptions = await session.client.hooks.list();
+    return emit(io, subscriptions.map(describe));
+}
+/**
+ * What is set up, what is not, and what is pointing somewhere else.
+ *
+ * Read-only, so it needs no confirmation and no write budget — the point is
+ * that somebody can run it on a real organisation without consequences.
+ */
+async function check(io, session, input) {
+    const { statuses, hub } = await assess(session, input);
+    const missing = statuses.filter((s) => s.state === "missing");
+    const elsewhere = statuses.filter((s) => s.state === "elsewhere");
+    return emit(io, {
+        hub,
+        ok: missing.length === 0 && elsewhere.length === 0,
+        subscriptions: statuses.map(summarise),
+        // Separated because they need different verbs, and conflating them is how
+        // somebody ends up with two subscriptions delivering the same event twice.
+        missing: missing.length,
+        pointingElsewhere: elsewhere.length,
+        ...(missing.length > 0 ? { hint: "pharos hooks create --hub <url> --user <u> --password <p> --yes" } : {}),
+        ...(elsewhere.length > 0
+            ? { repointHint: "pharos hooks repoint --hub <url> --user <u> --password <p> --yes" }
+            : {}),
+    });
+}
+async function create(io, session, input) {
+    const { statuses, hub, projectId, credentials } = await assess(session, input, {
+        needCredentials: true,
+    });
+    const missing = statuses.filter((s) => s.state === "missing");
+    if (missing.length === 0) {
+        return emit(io, { applied: false, action: "nothingMissing", hub });
+    }
+    const stop = approve(io, session, {
+        what: `create ${missing.length} service hook subscription(s) pointing at ${hub}`,
+        would: {
+            action: "createSubscriptions",
+            hub,
+            subscriptions: missing.map((s) => s.required.label),
+        },
+    });
+    if (stop !== undefined)
+        return stop;
+    const created = [];
+    for (const status of missing) {
+        const subscription = await session.client.hooks.create({
+            eventType: status.required.eventType,
+            projectId,
+            url: hub,
+            basicAuthUsername: credentials.user,
+            basicAuthPassword: credentials.password,
+            ...(status.required.repositoryId === undefined
+                ? {}
+                : { repositoryId: status.required.repositoryId }),
+        });
+        created.push(subscription.id);
+    }
+    return emit(io, { applied: true, action: "created", hub, count: created.length, ids: created });
+}
+/**
+ * Move existing subscriptions to a new URL.
+ *
+ * The verb a hostname change needs. Moving a hub means re-pointing every
+ * subscription, and there are six — which is also why doing it by hand is where
+ * one gets forgotten and realtime half-works.
+ */
+async function repoint(io, session, input) {
+    const { statuses, hub, credentials } = await assess(session, input, { needCredentials: true });
+    const moving = statuses.filter((s) => s.state === "elsewhere" && s.existing !== undefined);
+    if (moving.length === 0) {
+        return emit(io, { applied: false, action: "nothingToRepoint", hub });
+    }
+    const stop = approve(io, session, {
+        what: `re-point ${moving.length} subscription(s) to ${hub}`,
+        would: {
+            action: "repointSubscriptions",
+            to: hub,
+            subscriptions: moving.map((s) => ({ event: s.required.label, from: s.currentUrl })),
+        },
+    });
+    if (stop !== undefined)
+        return stop;
+    const moved = [];
+    for (const status of moving) {
+        // The password is re-sent, never carried over: Azure DevOps returns it
+        // masked as `********`, so a read-modify-write would send that literal
+        // string and every delivery would 401 while the subscription still read
+        // as enabled.
+        const updated = await session.client.hooks.repoint(status.existing, hub, credentials.user, credentials.password);
+        moved.push(updated.id);
+    }
+    return emit(io, { applied: true, action: "repointed", hub, count: moved.length, ids: moved });
+}
+async function remove(io, session, id) {
+    if (id === undefined || id === "") {
+        throw usageError("Which subscription? `pharos hooks delete <id>` — ids come from `hooks list`.");
+    }
+    const stop = approve(io, session, {
+        what: `delete service hook subscription ${id}`,
+        would: { action: "deleteSubscription", id },
+    });
+    if (stop !== undefined)
+        return stop;
+    await session.client.hooks.remove(id);
+    return emit(io, { applied: true, action: "deleted", id });
+}
+// MARK: - Shared assessment
+/**
+ * Resolve the project GUID, the wiki's repository GUID, and the current state.
+ *
+ * The wiki repository GUID is the whole reason this is not a browser job, and
+ * it comes from the Wiki API rather than the git one — the repositories
+ * endpoint does not list wiki repos at all.
+ */
+async function assess(session, input, options = {}) {
+    const hub = input.hub ?? "";
+    if (hub === "") {
+        throw usageError("Which hub? Pass --hub https://your-hub.example/hooks/ado — the URL Azure DevOps should POST to.");
+    }
+    const credentials = { user: input.user ?? "", password: input.password ?? "" };
+    if (options.needCredentials === true && (credentials.user === "" || credentials.password === "")) {
+        throw usageError("A subscription needs the hub's webhook credentials — pass --user and --password. They must "
+            + "match what the hub is configured with (PHAROS_WEBHOOK_USER / PHAROS_WEBHOOK_PASSWORD), "
+            + "or Azure DevOps will deliver and the hub will answer 401.");
+    }
+    const wiki = await session.wikiForLinking().catch(() => undefined);
+    const wikis = await session.wiki.listWikis().catch(() => []);
+    const repositoryId = wikis.find((w) => w.name === wiki?.name)?.repositoryId;
+    const projectId = wiki?.projectId ?? wikis[0]?.projectId ?? "";
+    if (projectId === "") {
+        throw usageError("Could not resolve the project GUID — a subscription cannot be scoped without it.");
+    }
+    const existing = await session.client.hooks.list();
+    const statuses = subscriptionStatus(existing, requiredSubscriptions(repositoryId), {
+        projectId,
+        url: hub,
+    });
+    return { statuses, hub, projectId, credentials };
+}
+function summarise(status) {
+    return {
+        event: status.required.eventType,
+        what: status.required.label,
+        state: status.state,
+        ...(status.existing === undefined ? {} : { id: status.existing.id }),
+        ...(status.currentUrl === undefined ? {} : { currentUrl: status.currentUrl }),
+    };
+}
+function describe(subscription) {
+    return {
+        id: subscription.id,
+        eventType: subscription.eventType,
+        status: subscription.status,
+        url: subscription.consumerInputs?.["url"],
+        projectId: subscription.publisherInputs?.["projectId"],
+        // Present only on git.push, and its absence there means `[Any]` — every
+        // push in the project, which is the wrong default rather than a detail.
+        repository: subscription.publisherInputs?.["repository"],
+    };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/commands/hooks.js.map

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

package/dist/commands/image.d.ts

@@ -0,0 +1,44 @@
+import { type ExitCode, type Io } from "../output.js";
+import type { Session } from "../session.js";
+/**
+ * `pharos image <file>` and `pharos wiki image <file>` — put a picture INSIDE
+ * the text.
+ *
+ * ## Why this is not `pharos attach`
+ *
+ * They look like the same verb and they are not, and the difference is the
+ * reason this exists.
+ *
+ * `attach` uploads bytes **and adds an `AttachedFile` relation**, so the file
+ * appears in the work item's Attachments list. An inline image has **no
+ * relation at all** — measured on #333: two screenshots pasted into a
+ * description gave `relations: 0` and `attachments: []`. It is an `![](…)` in
+ * the field text and nothing else, which is why the Attachments list is right
+ * to show nothing and why every piece of machinery that works from relations
+ * cannot see it.
+ *
+ * So: `attach` for a file somebody will open, `image` for a picture somebody
+ * will look at while reading. Using the wrong one is not fatal, but it puts a
+ * screenshot in the file list or a spreadsheet in the middle of a sentence.
+ *
+ * ## Two endpoints, and they are not interchangeable
+ *
+ * A **work item** image goes to `POST wit/attachments` and comes back with a
+ * GUID url, so two files called `image.png` are simply two attachments.
+ *
+ * A **wiki** image goes to `PUT wiki/wikis/{wiki}/attachments?name=`, whose body
+ * must be BASE64 (Microsoft's spec says stream; the server disagrees with a 500),
+ * and which writes a file into a git repository — so the NAME is the identity
+ * and a second `image.png` overwrites the first. The name is made unique here
+ * before it is sent.
+ */
+export interface ImageCommandOptions {
+    /** Alt text. Defaults to the file's own name, which is what a screenshot has. */
+    alt: string | undefined;
+    allowOversize: boolean;
+}
+/** `pharos image <file>` — for a work item description or comment. */
+export declare function runImage(io: Io, session: Session, cwd: string, positionals: readonly string[], options: ImageCommandOptions): Promise<ExitCode>;
+/** `pharos wiki image <file>` — for a wiki page or a wiki page comment. */
+export declare function runWikiImage(io: Io, session: Session, cwd: string, positionals: readonly string[], options: ImageCommandOptions): Promise<ExitCode>;
+//# sourceMappingURL=image.d.ts.map

package/dist/commands/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/commands/image.ts"],"names":[],"mappings":"AAKA,OAAO,EAA8B,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,sEAAsE;AACtE,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CA6BnB;AAED,2EAA2E;AAC3E,wBAAsB,YAAY,CAChC,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAyCnB"}

package/dist/commands/image.js

@@ -0,0 +1,114 @@
+import { readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { uniqueWikiAttachmentName } from "@floh-solutions/ado-core";
+import { emit, emitText, usageError } from "../output.js";
+/** `pharos image <file>` — for a work item description or comment. */
+export async function runImage(io, session, cwd, positionals, options) {
+    const { path, bytes, name } = await readImage(cwd, positionals[0], "pharos image ./shot.png");
+    const alt = options.alt ?? altTextFor(name);
+    if (session.previewOnly) {
+        return report(io, session, {
+            applied: false,
+            dryRun: true,
+            target: "workItem",
+            name,
+            bytes: bytes.length,
+            markdown: `![${alt}](…)`,
+            path,
+        });
+    }
+    const uploaded = await session.client.attachments.upload(name, bytes, {
+        allowOversize: options.allowOversize,
+    });
+    return report(io, session, {
+        applied: true,
+        target: "workItem",
+        name,
+        bytes: bytes.length,
+        url: uploaded.url,
+        markdown: `![${alt}](${uploaded.url})`,
+        path,
+    });
+}
+/** `pharos wiki image <file>` — for a wiki page or a wiki page comment. */
+export async function runWikiImage(io, session, cwd, positionals, options) {
+    const { path, bytes, name } = await readImage(cwd, positionals[0], "pharos wiki image ./diagram.png");
+    const alt = options.alt ?? altTextFor(name);
+    // **Unique before it is sent.** A wiki attachment is a file in a git repo, so
+    // the name IS the identity: a second `image.png` lands on the first and every
+    // page pointing at it silently changes picture.
+    const unique = uniqueWikiAttachmentName(name, Date.now());
+    if (session.previewOnly) {
+        return report(io, session, {
+            applied: false,
+            dryRun: true,
+            target: "wiki",
+            name: unique,
+            bytes: bytes.length,
+            markdown: `![${alt}](/.attachments/${unique})`,
+            path,
+        });
+    }
+    const wiki = await session.wikiIdentifier();
+    const created = await session.wiki.createAttachment(wiki, unique, bytes);
+    return report(io, session, {
+        applied: true,
+        target: "wiki",
+        wiki,
+        name: created.name,
+        bytes: bytes.length,
+        // Repo-relative, NOT an absolute url. A page referencing an absolute
+        // `wit/attachments` url renders for anyone with a session and breaks for
+        // everybody else.
+        attachmentPath: created.path,
+        markdown: `![${alt}](${created.path})`,
+        path,
+    });
+}
+async function readImage(cwd, given, example) {
+    if (given === undefined) {
+        throw usageError(`Which file? \`${example}\`.`);
+    }
+    const path = resolve(cwd, given);
+    let bytes;
+    try {
+        bytes = await readFile(path);
+    }
+    catch (error) {
+        // Exit 2, not 1: a missing file is the call being wrong, and repeating it
+        // unchanged will never work.
+        throw usageError(`Cannot read "${given}": ${error instanceof Error ? error.message : error}`, {
+            path,
+        });
+    }
+    return { path, bytes, name: basename(path) };
+}
+/**
+ * Alt text worth reading, from a file name.
+ *
+ * `Screenshot 2026-08-06 at 14.02.11.png` → `Screenshot 2026-08-06 at 14.02.11`.
+ * Not brilliant, and better than `image.png` or nothing: alt text is what
+ * somebody using a screen reader gets instead of the picture, and it is what
+ * every renderer shows when the image fails to load.
+ */
+function altTextFor(fileName) {
+    const dot = fileName.lastIndexOf(".");
+    const stem = dot > 0 ? fileName.slice(0, dot) : fileName;
+    return stem.trim() === "" ? "image" : stem;
+}
+function report(io, session, result) {
+    if (session.pretty) {
+        const where = result.target === "wiki" ? "the wiki" : "this project's work item attachments";
+        emitText(io, result.dryRun === true
+            ? `Would upload ${result.name} (${result.bytes} bytes) to ${where}.`
+            : `Uploaded ${result.name} (${result.bytes} bytes) to ${where}.`);
+        emitText(io, "");
+        // The markdown is the ANSWER, not a detail of it — the whole point of the
+        // verb is the line you paste into a description, a comment or a page.
+        emitText(io, result.markdown);
+        return 0;
+    }
+    emit(io, result);
+    return 0;
+}
+//# sourceMappingURL=image.js.map

package/dist/commands/image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../../src/commands/image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAA0B,MAAM,cAAc,CAAC;AA0ClF,sEAAsE;AACtE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,EAAM,EACN,OAAgB,EAChB,GAAW,EACX,WAA8B,EAC9B,OAA4B;IAE5B,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,yBAAyB,CAAC,CAAC;IAC9F,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAE5C,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE;YACzB,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,IAAI;YACZ,MAAM,EAAE,UAAU;YAClB,IAAI;YACJ,KAAK,EAAE,KAAK,CAAC,MAAM;YACnB,QAAQ,EAAE,KAAK,GAAG,MAAM;YACxB,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;QACpE,aAAa,EAAE,OAAO,CAAC,aAAa;KACrC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE;QACzB,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,UAAU;QAClB,IAAI;QACJ,KAAK,EAAE,KAAK,CAAC,MAAM;QACnB,GAAG,EAAE,QAAQ,CAAC,GAAG;QACjB,QAAQ,EAAE,KAAK,GAAG,KAAK,QAAQ,CAAC,GAAG,GAAG;QACtC,IAAI;KACL,CAAC,CAAC;AACL,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,EAAM,EACN,OAAgB,EAChB,GAAW,EACX,WAA8B,EAC9B,OAA4B;IAE5B,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,SAAS,CAC3C,GAAG,EACH,WAAW,CAAC,CAAC,CAAC,EACd,iCAAiC,CAClC,CAAC;IACF,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAE5C,8EAA8E;IAC9E,8EAA8E;IAC9E,gDAAgD;IAChD,MAAM,MAAM,GAAG,wBAAwB,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAE1D,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE;YACzB,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,IAAI;YACZ,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,KAAK,CAAC,MAAM;YACnB,QAAQ,EAAE,KAAK,GAAG,mBAAmB,MAAM,GAAG;YAC9C,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;IAC5C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAEzE,OAAO,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE;QACzB,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,MAAM;QACd,IAAI;QACJ,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,KAAK,EAAE,KAAK,CAAC,MAAM;QACnB,qEAAqE;QACrE,yEAAyE;QACzE,kBAAkB;QAClB,cAAc,EAAE,OAAO,CAAC,IAAI;QAC5B,QAAQ,EAAE,KAAK,GAAG,KAAK,OAAO,CAAC,IAAI,GAAG;QACtC,IAAI;KACL,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,SAAS,CACtB,GAAW,EACX,KAAyB,EACzB,OAAe;IAEf,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,UAAU,CAAC,iBAAiB,OAAO,KAAK,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACjC,IAAI,KAAa,CAAC;IAClB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,0EAA0E;QAC1E,6BAA6B;QAC7B,MAAM,UAAU,CAAC,gBAAgB,KAAK,MAAM,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE;YAC5F,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,UAAU,CAAC,QAAgB;IAClC,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IACzD,OAAO,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC;AAeD,SAAS,MAAM,CAAC,EAAM,EAAE,OAAgB,EAAE,MAAmB;IAC3D,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,KAAK,GACT,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,sCAAsC,CAAC;QACjF,QAAQ,CACN,EAAE,EACF,MAAM,CAAC,MAAM,KAAK,IAAI;YACpB,CAAC,CAAC,gBAAgB,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,KAAK,cAAc,KAAK,GAAG;YACpE,CAAC,CAAC,YAAY,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,KAAK,cAAc,KAAK,GAAG,CACnE,CAAC;QACF,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACjB,0EAA0E;QAC1E,sEAAsE;QACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9B,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACjB,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/commands/import.d.ts

@@ -0,0 +1,51 @@
+import { type ExitCode, type Io } from "../output.js";
+import type { Session } from "../session.js";
+/**
+ * `pharos wiki import <file…>` — documents in, wiki pages out.
+ *
+ * ## What it is for
+ *
+ * The macOS app grew this in #641: pick files, name them, choose one parent, and
+ * each becomes a page. Everything about it that is a RULE rather than a window —
+ * how a file name becomes a page name, what happens when two files want the same
+ * name, what happens when the page already exists — is the same here, because
+ * getting those wrong loses somebody's work either way.
+ *
+ * ## Where the conversion comes from
+ *
+ * `.md` and `.txt` are copied VERBATIM. A markdown file is already the target
+ * format and anything done to it on the way in would be reformatting a document
+ * somebody wrote deliberately.
+ *
+ * `.docx`, `.pdf`, `.rtf`, `.html` need converting, and that converter is Swift:
+ * it lives in `PharosCore`, has thirty-odd tests behind it and was measured
+ * against 246 real `.docx` files. **This shells out to it rather than
+ * reimplementing it**, because a second converter in TypeScript would be a
+ * second set of answers to "what does this document say", and the one that
+ * drifts is the one nobody is looking at.
+ *
+ * The helper is `pharos-convert`. When it is not on PATH, `.md` and `.txt`
+ * still import and everything else is refused **by name, with the reason** —
+ * rather than half-importing, which is the failure that would be worth
+ * complaining about.
+ *
+ * ## The rules that stop it losing work
+ *
+ * - **A collision SKIPS and says so.** A wiki page write with an empty version
+ *   is a create, so writing over an existing page is silent data loss.
+ * - **Names are settled against the batch as well as the wiki.** Importing
+ *   `Notes.docx` and `Notes.pdf` together is two files wanting one page name;
+ *   checking only the server would make that one page written twice, inside a
+ *   single command, faster than anybody could see.
+ * - **An empty document is refused.** A scanned PDF carries no text at all —
+ *   PDFKit hands back an empty string and no error — and an empty page would
+ *   look like a successful import until somebody opened it.
+ */
+export interface ImportCommandOptions {
+    /** The wiki path everything lands under. Empty is the top level. */
+    under: string | undefined;
+    /** Override the page name. Only meaningful for a single file. */
+    as: string | undefined;
+}
+export declare function runWikiImport(io: Io, session: Session, cwd: string, positionals: readonly string[], options: ImportCommandOptions): Promise<ExitCode>;
+//# sourceMappingURL=import.d.ts.map

package/dist/commands/import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../src/commands/import.ts"],"names":[],"mappings":"AAOA,OAAO,EAA8B,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAI7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,iEAAiE;IACjE,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;CACxB;AASD,wBAAsB,aAAa,CACjC,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,QAAQ,CAAC,CA6GnB"}

package/dist/commands/import.js

@@ -0,0 +1,190 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import { promisify } from "node:util";
+import { AdoNotFoundError } from "@floh-solutions/ado-core";
+import { emit, emitText, usageError } from "../output.js";
+const run = promisify(execFile);
+export async function runWikiImport(io, session, cwd, positionals, options) {
+    if (positionals.length === 0) {
+        throw usageError("Which files? `pharos wiki import ./notes.md ./report.docx --under /Guides`.");
+    }
+    if (options.as !== undefined && positionals.length > 1) {
+        throw usageError("`--as` names ONE page, so it cannot be used with several files.");
+    }
+    const wiki = await session.wikiIdentifier();
+    const parent = normalisePath(options.under ?? "");
+    // Every path already in the wiki, for the collision check. One call, and the
+    // check is repeated per file against the growing set so the batch cannot
+    // collide with itself.
+    const taken = new Set();
+    for (const path of await existingPaths(session, wiki)) {
+        taken.add(path.toLowerCase());
+    }
+    const outcomes = [];
+    for (const given of positionals) {
+        const path = resolve(cwd, given);
+        const file = basename(path);
+        let converted;
+        try {
+            converted = await convert(path, file);
+        }
+        catch (error) {
+            outcomes.push({ file, skipped: error instanceof Error ? error.message : String(error) });
+            continue;
+        }
+        // **A NAME SOMEBODY TYPED IS NOT RENAMED.** A name DERIVED from a file name
+        // is counted up when it is taken — that is the same thing the app's staging
+        // list does, and importing `Notes.docx` beside `Notes.pdf` should give two
+        // pages rather than one refusal. But `--as` is an instruction, and quietly
+        // turning it into "… 2" writes a page nobody asked for under a name nobody
+        // chose. So an explicit name is allowed to collide, and collisions skip.
+        const explicit = options.as !== undefined;
+        const leaf = sanitise(options.as ?? converted.name);
+        const target = joinPath(parent, explicit ? leaf : freeName(leaf, taken, parent));
+        if (taken.has(target.toLowerCase())) {
+            outcomes.push({
+                file,
+                page: target,
+                skipped: `There is already a page at ${target}. It was left alone.`,
+            });
+            continue;
+        }
+        if (session.previewOnly) {
+            outcomes.push({ file, page: target, created: false });
+            taken.add(target.toLowerCase());
+            continue;
+        }
+        // ANCESTORS ARE NOT CREATED FOR YOU — writing `/A/B` when `/A` does not
+        // exist is refused by Azure DevOps. Made once per missing ancestor, empty,
+        // which is what the website does when you add a page under a folder.
+        for (const ancestor of ancestorsOf(target)) {
+            if (taken.has(ancestor.toLowerCase()))
+                continue;
+            try {
+                await session.wiki.writePage(wiki, ancestor, "");
+            }
+            catch {
+                // Already there, or refused for a reason the child's own write will
+                // report properly. Either way it is not this loop's business.
+            }
+            taken.add(ancestor.toLowerCase());
+        }
+        await session.wiki.writePage(wiki, target, converted.markdown);
+        taken.add(target.toLowerCase());
+        outcomes.push({ file, page: target, created: true });
+    }
+    const created = outcomes.filter((outcome) => outcome.created === true).length;
+    const skipped = outcomes.filter((outcome) => outcome.skipped !== undefined).length;
+    if (session.pretty) {
+        for (const outcome of outcomes) {
+            emitText(io, outcome.skipped !== undefined
+                ? `skipped  ${outcome.file} — ${outcome.skipped}`
+                : `${outcome.created === true ? "created" : "would create"}  ${outcome.page}`);
+        }
+        emitText(io, "");
+        emitText(io, `${created} created, ${skipped} skipped.`);
+        return skipped > 0 && created === 0 ? 3 : 0;
+    }
+    emit(io, {
+        applied: !session.previewOnly,
+        dryRun: session.previewOnly ? true : undefined,
+        wiki,
+        under: parent === "" ? "/" : parent,
+        created,
+        skipped,
+        pages: outcomes,
+    });
+    // Exit 3 — a guard here refused — only when NOTHING landed. A partial batch
+    // did real work and reporting it as a failure would invite a blind retry that
+    // collides with the pages it just made.
+    return skipped > 0 && created === 0 ? 3 : 0;
+}
+/** A document, as markdown. */
+async function convert(path, file) {
+    const extension = extname(file).toLowerCase();
+    const stem = file.slice(0, file.length - extension.length) || file;
+    if (extension === ".md" || extension === ".markdown" || extension === ".txt") {
+        const markdown = await readFile(path, "utf8");
+        if (markdown.trim() === "") {
+            throw new Error(`${file} has no text in it, so there is nothing to make a page from.`);
+        }
+        return { name: stem, markdown };
+    }
+    try {
+        const { stdout } = await run("pharos-convert", [path], { maxBuffer: 32 * 1024 * 1024 });
+        const parsed = JSON.parse(stdout);
+        return parsed;
+    }
+    catch (error) {
+        const failure = error;
+        if (failure.code === "ENOENT") {
+            throw new Error(`${file} needs \`pharos-convert\`, which is not on PATH. `
+                + "Markdown and text import without it; Word documents and PDFs need it because the "
+                + "converter is shared with the macOS app rather than written twice.");
+        }
+        // The helper's own sentence, forwarded verbatim — it already says what is
+        // wrong and what to do, including the scanned-PDF case.
+        const said = (failure.stderr ?? "").trim();
+        throw new Error(said === "" ? `${file} could not be converted.` : said);
+    }
+}
+/** Every page path already in the wiki. */
+async function existingPaths(session, wiki) {
+    try {
+        const ids = await session.wiki.pageIdsByPath(wiki);
+        return [...ids.keys()];
+    }
+    catch (error) {
+        if (error instanceof AdoNotFoundError)
+            return [];
+        throw error;
+    }
+}
+/** Leading slash, no trailing one. The API is inconsistent about both. */
+function normalisePath(path) {
+    let trimmed = path.trim();
+    while (trimmed.endsWith("/"))
+        trimmed = trimmed.slice(0, -1);
+    if (trimmed === "")
+        return "";
+    return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+function joinPath(parent, leaf) {
+    const head = normalisePath(parent);
+    const tail = leaf.replace(/^\/+|\/+$/g, "");
+    return head === "" ? `/${tail}` : `${head}/${tail}`;
+}
+/**
+ * A page name a wiki path can hold.
+ *
+ * **The slash is the one that matters**: a path is slash-separated, so a file
+ * called `Q1/Q2 review` would otherwise create a page called `Q2 review` nested
+ * under a brand-new `Q1`, in a place nobody chose and with `--under` silently
+ * overruled.
+ */
+function sanitise(name) {
+    const cleaned = name
+        .replace(/[/\\:*?"<>|#\t\n\r]+/g, "-")
+        .replace(/^[\s\-.]+|[\s\-.]+$/g, "");
+    return cleaned === "" ? "Untitled" : cleaned;
+}
+/** A name not already taken, counting from 2 because the unnumbered one is first. */
+function freeName(name, taken, parent) {
+    if (!taken.has(joinPath(parent, name).toLowerCase()))
+        return name;
+    let suffix = 2;
+    while (taken.has(joinPath(parent, `${name} ${suffix}`).toLowerCase()))
+        suffix += 1;
+    return `${name} ${suffix}`;
+}
+/** `/A/B/C` → `["/A", "/A/B"]`, outermost first. */
+function ancestorsOf(path) {
+    const parts = normalisePath(path).split("/").filter((part) => part !== "");
+    const out = [];
+    for (let index = 1; index < parts.length; index += 1) {
+        out.push(`/${parts.slice(0, index).join("/")}`);
+    }
+    return out;
+}
+//# sourceMappingURL=import.js.map

package/dist/commands/import.js.map

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