@hakopod/cloud 0.0.0-bootstrap → 0.1.0-alpha.3

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,67 @@
+# Hakopod Cloud CLI
+
+Deploy a committed Git repository to Hakopod Cloud or your own Hakopod installation.
+Requires Node.js 22.12+ and Git. This package uses the shared engine API; it does not
+download or execute another binary during npm installation.
+
+```sh
+npx @hakopod/cloud deploy
+# Or point it at your own dashboard:
+npx @hakopod/cloud deploy --url https://hakopod.example.com
+```
+
+The first run opens browser sign-in. Create an account if needed, compare the
+terminal code, and choose one project/environment or ready Cloud workspace.
+If no destination is ready, open dashboard setup from the consent page, finish
+setup, return, and refresh destinations. Codes expire after ten minutes; repeat
+login if setup takes longer. Cloud admission, email verification, membership and
+MFA requirements still apply. A project administrator or Cloud workspace owner
+must connect Git and authorize a new application source.
+
+The deploy command checks that your working tree is clean and the current branch
+is pushed to `origin`, detects the framework remotely, and lets you review or edit
+its commands, service port and public access. GitHub.com and GitLab.com are supported.
+It shows the exact generated workflow and requirements before writing it, then
+writes to the repository default branch. When deploying that branch, it also
+fast-forwards your local checkout to the reviewed workflow commit. Concurrent remote
+or local edits stop this step for review. Builds run in your Git provider's CI.
+
+You review the deployment plan before its digest-pinned image is deployed. The CLI
+waits for the deployment's terminal status. Failed builds, failed deployments and
+Cloud Team approvals do not report success. Approval must be completed in Cloud.
+Run the same command after interruption to resume an accepted build/deployment.
+
+```sh
+npx @hakopod/cloud login --url https://cloud.hakopod.com
+npx @hakopod/cloud deploy --name my-app --context apps/web
+npx @hakopod/cloud deploy --build BUILD_ID  # link an existing build for this exact source/scope
+npx @hakopod/cloud status
+npx @hakopod/cloud logout
+```
+
+`--no-browser` prints the sign-in URL without opening it. `--yes` accepts the
+printed configuration, workflow and deployment reviews; it does not bypass browser
+consent or server policy. Noninteractive defaults use Cloud, a small private web
+service and the detected commands. Advanced runtime variables, secret bindings,
+multiple services, architecture and resource settings remain editable in the
+shared dashboard; linked builds preserve those settings.
+
+Credentials and resumable deployment state live outside the source repository in
+`~/.config/hakopod/npm`, separately for each exact installation origin. Set
+`HAKOPOD_CLI_HOME` to use another protected directory. Files are written atomically
+with owner-only permissions; Windows uses the account profile's directory ACLs.
+Sessions expire after twelve hours and can be revoked in account security. Logout
+attempts server revocation and always removes local credentials. Account login happens in the browser. Before deployment, missing application
+secrets can be entered with hidden terminal input or explicitly generated.
+Generation creates a random password, not a provider-issued API credential.
+Noninteractive runs stop with the missing names, including when using `--yes`.
+Secret values are sent directly to scoped storage and never saved in CLI state.
+Never commit CLI state to Git.
+
+Use an engine/Cloud server release containing npm CLI device-scope support. Older
+servers may expose only the image-based Go CLI API. That CLI remains available for
+TOML, machine API keys, logs and infrastructure administration.
+
+For local development: `npm test`, `npm pack`, then `npx --package ./hakopod-cloud-*.tgz hakopod-cloud --help`.
+The package archive contains only public JavaScript, this documentation and the
+Apache-2.0 license. CI tests it and inspects its package contents.

package/package.json

@@ -1,7 +1,30 @@
 {
   "name": "@hakopod/cloud",
-  "version": "0.0.0-bootstrap",
-  "description": "Placeholder to enable npm trusted publishing. Replaced by the first real release.",
+  "version": "0.1.0-alpha.3",
+  "description": "Guided Git deployments to Hakopod Cloud and self-hosted Hakopod",
+  "type": "module",
   "license": "Apache-2.0",
-  "private": false
+  "bin": {
+    "hakopod-cloud": "src/main.mjs"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hakopod/hakopod.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/core.mjs

@@ -0,0 +1,297 @@
+import { mkdir, open, readFile, rename, stat, unlink } from "node:fs/promises";
+import { constants } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+export const execute = promisify(execFile);
+export const cloud = "https://cloud.hakopod.com";
+export const clean = (value) =>
+  String(value).replace(/[\x00-\x1f\x7f-\x9f]/g, "");
+export function origin(value) {
+  const url = new URL(value);
+  if (
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    !["", "/"].includes(url.pathname) ||
+    !(
+      url.protocol === "https:" ||
+      (url.protocol === "http:" &&
+        ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))
+    )
+  )
+    throw new Error(
+      "Use an exact HTTPS dashboard origin, or HTTP on localhost.",
+    );
+  return url.origin;
+}
+export function remote(value) {
+  const match =
+    /^(?:git@(github\.com|gitlab\.com):|https:\/\/(github\.com|gitlab\.com)\/|ssh:\/\/git@(github\.com|gitlab\.com)\/)([A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+?)(?:\.git)?$/.exec(
+      value,
+    );
+  if (!match)
+    throw new Error(
+      "Use a GitHub.com or GitLab.com origin without credentials in its URL.",
+    );
+  const host = match[1] || match[2] || match[3];
+  const repository = match[4].replace(/\.git$/, "");
+  if (
+    repository.split("/").some((part) => part === "." || part === "..") ||
+    (host === "github.com" && repository.split("/").length !== 2)
+  )
+    throw new Error("Invalid Git repository path.");
+  return { provider: host === "github.com" ? "github" : "gitlab", repository };
+}
+export async function git(args, cwd = process.cwd()) {
+  try {
+    return (
+      await execute("git", args, {
+        cwd,
+        timeout: 30000,
+        maxBuffer: 1024 * 1024,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+      })
+    ).stdout.trim();
+  } catch {
+    throw new Error(
+      "Git could not complete the check. Verify repository access and your local Git credentials.",
+    );
+  }
+}
+export async function repository(cwd = process.cwd(), requirePushed = true) {
+  const root = await git(["rev-parse", "--show-toplevel"], cwd);
+  const source = remote(await git(["remote", "get-url", "origin"], root));
+  const branch = await git(["symbolic-ref", "--short", "HEAD"], root);
+  const commit = await git(["rev-parse", "HEAD"], root);
+  if (requirePushed) {
+    if (await git(["status", "--porcelain"], root))
+      throw new Error(
+        "Commit or stash local changes first. This command deploys only committed, pushed Git files.",
+      );
+    const published = await git(
+      ["ls-remote", "--exit-code", "origin", `refs/heads/${branch}`],
+      root,
+    );
+    if (published.split(/\s/)[0] !== commit)
+      throw new Error(
+        "Push this branch before deploying. Its remote HEAD must match your local commit.",
+      );
+  }
+  return { root, branch, commit, ...source };
+}
+export const configRoot = () =>
+  process.env.HAKOPOD_CLI_HOME || join(homedir(), ".config", "hakopod", "npm");
+export const key = (value) => createHash("sha256").update(value).digest("hex");
+export async function readPrivate(file) {
+  let handle;
+  try {
+    handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const info = await handle.stat();
+    if (
+      (process.getuid && info.uid !== process.getuid()) ||
+      !info.isFile() ||
+      info.size > 1024 * 1024 ||
+      (process.platform !== "win32" && info.mode & 0o077)
+    )
+      throw new Error("CLI state must be a private file (chmod 600).");
+    return JSON.parse(await handle.readFile("utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  } finally {
+    await handle?.close();
+  }
+}
+export async function writePrivate(file, data) {
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${randomUUID()}`;
+  const handle = await open(temporary, "wx", 0o600);
+  try {
+    await handle.writeFile(JSON.stringify(data, null, 2) + "\n");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename(temporary, file);
+  } finally {
+    await unlink(temporary).catch(() => {});
+  }
+}
+export const profilePath = (target) =>
+  join(configRoot(), `profile-${key(origin(target))}.json`);
+export const statePath = (target, scope, root) =>
+  join(
+    configRoot(),
+    `deploy-${key(JSON.stringify([origin(target), scope, root]))}.json`,
+  );
+export class APIError extends Error {
+  constructor(status, body) {
+    super(
+      clean(
+        body?.error?.message ||
+          body?.error ||
+          `API request failed (${status}).`,
+      ),
+    );
+    this.status = status;
+    this.code = body?.error?.code || body?.error;
+    this.details = body?.error;
+  }
+}
+export class API {
+  constructor(target, profile, transport = fetch) {
+    this.origin = origin(target);
+    this.profile = profile;
+    this.transport = transport;
+  }
+  async call(
+    path,
+    body,
+    { method = body === undefined ? "GET" : "POST", idempotency } = {},
+  ) {
+    if (
+      !/^\/[A-Za-z0-9/?=&%_.:-]+$/.test(path) ||
+      path.startsWith("//") ||
+      path.split("/").includes("..")
+    )
+      throw new Error("Invalid API path.");
+    if (this.profile && this.profile.origin !== this.origin)
+      throw new Error(
+        "Credentials belong to a different installation. Sign in again.",
+      );
+    const headers = { Accept: "application/json" };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    if (this.profile) {
+      headers.Authorization = `Bearer ${this.profile.token}`;
+      if (this.profile.scope_id)
+        headers["X-Hakopod-Workspace"] = this.profile.scope_id;
+    }
+    if (idempotency) headers["Idempotency-Key"] = idempotency;
+    let response;
+    try {
+      response = await this.transport(`${this.origin}/api/v1${path}`, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        redirect: "error",
+        signal: AbortSignal.timeout(35000),
+      });
+    } catch {
+      throw new Error(
+        "Cannot reach this installation. Any accepted work continues; run the command again to resume.",
+      );
+    }
+    const reader = response.body?.getReader();
+    const chunks = [];
+    let length = 0;
+    if (reader)
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        length += value.length;
+        if (length > 2 * 1024 * 1024) {
+          await reader.cancel();
+          throw new Error("API response exceeds the CLI limit.");
+        }
+        chunks.push(Buffer.from(value));
+      }
+    let result;
+    try {
+      result = JSON.parse(Buffer.concat(chunks).toString());
+    } catch {
+      throw new Error(
+        "This installation did not return JSON. Check the dashboard URL and server version.",
+      );
+    }
+    if (!response.ok) throw new APIError(response.status, result);
+    return result;
+  }
+}
+export async function openBrowser(url) {
+  const command =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "rundll32"
+        : "xdg-open";
+  const args =
+    process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
+  await execute(command, args, { timeout: 5000 }).catch(() => {});
+}
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function deviceLogin(
+  api,
+  { show, launch = openBrowser, wait = sleep, now = Date.now } = {},
+) {
+  const challenge = await api.call("/auth/device/start", {});
+  const link = new URL(challenge.verification_uri_complete);
+  if (
+    link.origin !== api.origin ||
+    link.pathname !== "/login/device" ||
+    link.username ||
+    link.password ||
+    link.hash ||
+    link.searchParams.get("user_code") !== challenge.user_code ||
+    !/^[A-Z2-7]{4}-[A-Z2-7]{4}$/.test(challenge.user_code) ||
+    !/^[a-f0-9]{64}$/.test(challenge.device_code)
+  )
+    throw new Error(
+      "The server returned an invalid browser authorization link.",
+    );
+  if (
+    !Number.isInteger(challenge.expires_in) ||
+    challenge.expires_in < 1 ||
+    challenge.expires_in > 900 ||
+    !Number.isInteger(challenge.interval) ||
+    challenge.interval < 5 ||
+    challenge.interval > 30
+  )
+    throw new Error("The server returned invalid authorization timing.");
+  show(
+    `Sign in or create an account, choose a destination, and approve code ${challenge.user_code}.\n${link.href}`,
+  );
+  await launch(link.href);
+  const deadline = now() + challenge.expires_in * 1000;
+  let interval = challenge.interval;
+  while (now() < deadline) {
+    await wait(interval * 1000);
+    if (now() >= deadline) break;
+    try {
+      const result = await api.call("/auth/device/token", {
+        device_code: challenge.device_code,
+      });
+      if (
+        !/^hs_[a-f0-9]{32}_[a-f0-9]{64}$/.test(result.access_token) ||
+        result.user?.credential_type !== "cli" ||
+        !result.user.project ||
+        !result.user.environment ||
+        (result.scope_id && !/^[a-f0-9]{32}$/.test(result.scope_id)) ||
+        !(Date.parse(result.expires_at) > now())
+      )
+        throw new Error("The server returned an invalid scoped CLI session.");
+      return {
+        origin: api.origin,
+        token: result.access_token,
+        expires_at: result.expires_at,
+        scope_id: result.scope_id || "",
+        project: result.user.project,
+        environment: result.user.environment,
+      };
+    } catch (error) {
+      if (error.code === "authorization_pending") continue;
+      if (error.code === "slow_down") {
+        interval = Math.min(30, interval + 5);
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw new Error(
+    "Sign-in expired. Run hakopod-cloud login again to get a new code.",
+  );
+}

package/src/main.mjs

@@ -0,0 +1,490 @@
+#!/usr/bin/env node
+import { Writable } from "node:stream";
+import { parseArgs } from "node:util";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { basename } from "node:path";
+import { unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import {
+  API,
+  APIError,
+  cloud,
+  clean,
+  origin,
+  repository,
+  git,
+  profilePath,
+  statePath,
+  readPrivate,
+  writePrivate,
+  deviceLogin,
+  openBrowser,
+  sleep,
+} from "./core.mjs";
+
+const help = `Hakopod — deploy committed Git repositories
+
+  npx @hakopod/cloud deploy
+  npx @hakopod/cloud login --url https://hakopod.example.com
+  npx @hakopod/cloud status --url https://hakopod.example.com
+  npx @hakopod/cloud logout --url https://hakopod.example.com
+
+Options: --url <dashboard origin>  --name <application>  --context <directory>
+         --build <existing build ID>  --yes (accept displayed reviews)  --no-browser  --help
+
+Requires Node 22.12+, Git, and a pushed GitHub.com or GitLab.com branch.
+Cloud is the default for noninteractive use. Self-hosted uses the same APIs.
+Credentials are saved per installation with owner-only file permissions.
+`;
+let rl;
+const say = (value) => stdout.write(`${clean(value)}\n`);
+const show = (value) =>
+  stdout.write(
+    String(value).replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, "") + "\n",
+  );
+async function ask(label, fallback = "") {
+  if (!stdin.isTTY) {
+    if (fallback) return fallback;
+    throw new Error(`${label}: run in an interactive terminal.`);
+  }
+  rl ||= createInterface({ input: stdin, output: stdout });
+  return (
+    (
+      await rl.question(`${label}${fallback ? ` [${clean(fallback)}]` : ""}: `)
+    ).trim() || fallback
+  );
+}
+async function askSecret(label) {
+  if (!stdin.isTTY) throw new Error("Secret input requires an interactive terminal.");
+  rl?.close(); rl = undefined;
+  let muted = false;
+  const output = new Writable({ write(chunk, encoding, done) { if (!muted) stdout.write(chunk, encoding); done(); } });
+  const secretInput = createInterface({ input: stdin, output, terminal: true });
+  try {
+    const result = secretInput.question(`${label} (hidden): `);
+    muted = true;
+    return await result;
+  } finally { secretInput.close(); stdout.write("\n"); }
+}
+async function setupSecrets(api, config, plan) {
+  const missing = plan.missing_secrets || [];
+  if (!missing.length) return;
+  if (!stdin.isTTY) throw new Error(`Missing application secrets: ${missing.map(clean).join(", ")}. Save them in the dashboard or through POST /api/v1/secrets/{name}, then retry. No deployment was submitted.`);
+  for (const name of missing) {
+    say(`Missing secret: ${name}`);
+    const mode = await choose("Secret value", [
+      { label: "Enter an existing value (hidden)", value: "value" },
+      { label: "Generate a new random password (not a provider credential)", value: "generate" },
+      { label: "Cancel deployment", value: "cancel" },
+    ]);
+    if (mode === "cancel") throw new Error("Secret setup cancelled. No deployment was submitted.");
+    const body = mode === "generate" ? { generate: true } : { value: await askSecret(clean(name)) };
+    const query = new URLSearchParams({ project: config.project, environment: config.environment, application: plan.spec.name });
+    try { await api.call(`/secrets/${encodeURIComponent(name)}?${query}`, body); }
+    finally { delete body.value; }
+  }
+}
+async function choose(label, items) {
+  if (!items.length) throw new Error(`No ${label.toLowerCase()} available.`);
+  items.forEach((item, index) => say(`${index + 1}. ${item.label}`));
+  for (;;) {
+    const value = Number(await ask(label, items.length === 1 ? "1" : ""));
+    if (Number.isInteger(value) && items[value - 1])
+      return items[value - 1].value;
+    say("Choose one of the numbers above.");
+  }
+}
+async function confirm(label, yes) {
+  if (yes) {
+    say(`${label}: accepted with --yes`);
+    return;
+  }
+  if (!/^y(es)?$/i.test(await ask(`${label} (y/N)`, "n")))
+    throw new Error(
+      "Stopped. Saved configuration remains available for your next attempt.",
+    );
+}
+async function waitFor(read, finished, label, timeout = 30 * 60 * 1000) {
+  let previous = "";
+  const until = Date.now() + timeout;
+  while (Date.now() < until) {
+    const item = await read();
+    if (item.status !== previous) {
+      say(`${label}: ${item.status}`);
+      previous = item.status;
+    }
+    if (finished(item)) return item;
+    await sleep(5000);
+  }
+  throw new Error(
+    `${label} is still running. Use the same deploy command to resume, or status to inspect it.`,
+  );
+}
+async function main() {
+  const { values: flags, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      url: { type: "string" },
+      name: { type: "string" },
+      context: { type: "string" },
+      build: { type: "string" },
+      yes: { type: "boolean" },
+      "no-browser": { type: "boolean" },
+      help: { type: "boolean" },
+    },
+  });
+  if (flags.help) {
+    show(help);
+    return;
+  }
+  const command = positionals[0] || "deploy";
+  if (
+    positionals.length > 1 ||
+    !["deploy", "login", "logout", "status"].includes(command)
+  )
+    throw new Error(help);
+  let target = flags.url;
+  if (!target && stdin.isTTY) {
+    const kind = await choose("Deployment target", [
+      { label: "Hakopod Cloud", value: "cloud" },
+      { label: "Self-hosted Hakopod", value: "self" },
+    ]);
+    target = kind === "cloud" ? cloud : await ask("Self-hosted dashboard URL");
+  }
+  target = origin(target || cloud);
+  const file = profilePath(target);
+  let profile = await readPrivate(file);
+  if (command === "logout") {
+    if (profile) {
+      try {
+        await new API(target, profile).call("/auth/logout", {});
+        say("CLI session revoked.");
+      } catch {
+        say(
+          `Server revocation was unavailable. Revoke this session in ${target}/settings/security.`,
+        );
+      }
+      await unlink(file);
+      say("Removed local credentials.");
+    } else say("No saved login for this installation.");
+    return;
+  }
+  let api = new API(target, profile);
+  if (
+    command === "login" ||
+    !profile ||
+    Date.parse(profile.expires_at) <= Date.now()
+  )
+    profile = null;
+  if (profile) {
+    try {
+      const me = await api.call("/me");
+      if (
+        me.credential_type !== "cli" ||
+        me.project !== profile.project ||
+        me.environment !== profile.environment
+      )
+        throw new Error(
+          "The saved CLI destination no longer matches. Run login again.",
+        );
+    } catch (error) {
+      if (error.status === 401) profile = null;
+      else throw error;
+    }
+  }
+  if (!profile) {
+    profile = await deviceLogin(new API(target), {
+      show,
+      launch: flags["no-browser"] ? async () => {} : openBrowser,
+    });
+    await writePrivate(file, profile);
+    api = new API(target, profile);
+  }
+  say(`Destination: ${target} · ${profile.project} / ${profile.environment}`);
+  if (command === "login") return;
+  let source = await repository(process.cwd(), command !== "status");
+  const local = statePath(
+    target,
+    [profile.scope_id, profile.project, profile.environment],
+    source.root,
+  );
+  let saved = await readPrivate(local);
+  if (flags.build) {
+    if (!/^[a-f0-9]{32}$/.test(flags.build))
+      throw new Error("Use the build ID shown in the dashboard.");
+    if (saved?.build && saved.build !== flags.build)
+      throw new Error(
+        "This directory already has a linked build for this destination.",
+      );
+    const linked = await api.call(`/builds/${flags.build}`);
+    if (
+      linked.project !== profile.project ||
+      linked.environment !== profile.environment ||
+      linked.repository !== source.repository ||
+      linked.provider !== source.provider ||
+      linked.branch !== source.branch
+    )
+      throw new Error(
+        "Build does not match this repository and authorized destination.",
+      );
+    saved ||= { build: linked.id };
+    await writePrivate(local, saved);
+  }
+  if (command === "status") {
+    if (!saved?.build)
+      throw new Error(
+        "No saved deployment in this repository for this destination.",
+      );
+    const build = await api.call(`/builds/${saved.build}`);
+    say(`Application: ${build.name}`);
+    if (saved.run) {
+      const run = await api.call(`/builds/${saved.build}/runs/${saved.run}`);
+      say(`Build: ${run.status} ${run.conclusion}`);
+      if (run.deployment_id) {
+        const deployment = await api.call(`/deployments/${run.deployment_id}`);
+        say(`Deployment: ${deployment.status}`);
+      }
+    }
+    return;
+  }
+  let config;
+  if (saved?.build) {
+    config = await api.call(`/builds/${saved.build}`);
+    if (
+      config.repository !== source.repository ||
+      config.provider !== source.provider ||
+      config.branch !== source.branch ||
+      config.project !== profile.project ||
+      config.environment !== profile.environment
+    )
+      throw new Error(
+        "This directory is linked to another source or destination. Use a separate checkout or restore its original branch.",
+      );
+    if (
+      (flags.name && flags.name !== config.name) ||
+      (flags.context && flags.context !== config.context_path)
+    )
+      throw new Error(
+        "This deployment is already linked. Edit its build configuration in the dashboard before continuing.",
+      );
+  } else {
+    let connections = (await api.call("/git/connections")).items.filter(
+      (item) =>
+        item.provider === source.provider &&
+        item.enabled &&
+        item.capabilities.builds,
+    );
+    if (!connections.length) {
+      const url = `${target}/settings/git/connections/new`;
+      show(
+        `Connect ${source.provider} in the dashboard for this destination, then return here.\n${url}`,
+      );
+      if (!flags["no-browser"]) await openBrowser(url);
+      await ask("Press Enter after connecting Git", "continue");
+      connections = (await api.call("/git/connections")).items.filter(
+        (item) =>
+          item.provider === source.provider &&
+          item.enabled &&
+          item.capabilities.builds,
+      );
+    }
+    const connection_id = await choose(
+      "Git connection",
+      connections.map((item) => ({ label: item.name, value: item.id })),
+    );
+    const name =
+      flags.name ||
+      (await ask(
+        "Application name",
+        basename(source.root)
+          .toLowerCase()
+          .replace(/[^a-z0-9-]/g, "-")
+          .slice(0, 40),
+      ));
+    const context_path =
+      flags.context || (await ask("Directory inside repository", "."));
+    let input = {
+      project: profile.project,
+      environment: profile.environment,
+      name,
+      provider: source.provider,
+      repository: source.repository,
+      branch: source.branch,
+      connection_id,
+      context_path,
+      service: "web",
+      public: false,
+      auto_build: false,
+      auto_deploy: false,
+    };
+    const detected = await api.call("/builds/detect", input);
+    if (detected.commit_sha !== source.commit)
+      throw new Error(
+        "The remote branch changed during detection. Pull and review it, then retry.",
+      );
+    show(
+      `Detected ${detected.framework?.framework || "Dockerfile"} at ${source.commit}\n${(detected.warnings || []).join("\n")}`,
+    );
+    input = {
+      ...input,
+      mode: detected.mode,
+      framework: detected.framework,
+      dockerfile: detected.dockerfile,
+      port: detected.framework?.port || 8080,
+      size: "small",
+    };
+    if (input.framework) {
+      show(JSON.stringify(input.framework, null, 2));
+      if (
+        !flags.yes &&
+        /^y(es)?$/i.test(await ask("Edit detected commands? (y/N)", "n"))
+      ) {
+        for (const field of [
+          "install_command",
+          "build_command",
+          "start_command",
+          "output_directory",
+        ]) {
+          if (input.framework[field] !== undefined)
+            input.framework[field] = await ask(
+              field.replaceAll("_", " "),
+              input.framework[field],
+            );
+        }
+      }
+    }
+    input.port = Number(await ask("Service port", String(input.port)));
+    if (!Number.isInteger(input.port) || input.port < 1 || input.port > 65535)
+      throw new Error("Choose a service port between 1 and 65535.");
+    if (input.framework) input.framework.port = input.port;
+    input.public = /^y(es)?$/i.test(
+      await ask("Expose this web service publicly? (y/N)", "n"),
+    );
+    show(`Review build settings\n${JSON.stringify(input, null, 2)}`);
+    await confirm("Save these build settings", flags.yes);
+    // A create response can be lost. Discover the unique saved name before retrying.
+    const existing = (
+      await api.call(
+        `/builds?project=${encodeURIComponent(profile.project)}&environment=${encodeURIComponent(profile.environment)}`,
+      )
+    ).items.filter((item) => item.name === name);
+    if (existing.length)
+      throw new Error(
+        "A build with this name already exists. Rerun with --build plus its ID from the dashboard, or choose another application name.",
+      );
+    config = await api.call("/builds", input);
+    saved = { build: config.id };
+    await writePrivate(local, saved);
+  }
+  say(`Application: ${config.name} · ${source.repository} · ${source.branch}`);
+  if (config.installed_revision !== config.revision) {
+    const preview = await api.call(`/builds/${config.id}/preview`, {});
+    show(
+      `Workflow to write: ${preview.workflow_path}\n${preview.workflow}\nRequirements:\n${preview.requirements.join("\n")}`,
+    );
+    await confirm(
+      "Commit this workflow to the repository default branch (fast-forward locally if selected)",
+      flags.yes,
+    );
+    const installed = await api.call(`/builds/${config.id}/install`, {
+      expected_config_revision: config.revision,
+    });
+    config = installed.config;
+    if (!/^[a-f0-9]{40,64}$/.test(installed.commit_sha))
+      throw new Error("The provider returned an invalid workflow commit.");
+    if (!installed.workflow_branch)
+      throw new Error(
+        "The server must report the installed workflow branch. Upgrade this installation before continuing.",
+      );
+    if (installed.workflow_branch === source.branch) {
+      if (await git(["status", "--porcelain"], source.root))
+        throw new Error(
+          "Local files changed during review. Commit or stash them, pull the workflow commit, and rerun deploy.",
+        );
+      await git(["fetch", "origin", source.branch], source.root);
+      if (
+        (await git(["rev-parse", "FETCH_HEAD"], source.root)) !==
+        installed.commit_sha
+      )
+        throw new Error(
+          "The remote branch changed after workflow installation. Pull and review it before retrying.",
+        );
+      await git(["merge", "--ff-only", installed.commit_sha], source.root);
+      source = await repository(source.root);
+    }
+    say(
+      `Workflow installed on ${installed.workflow_branch}. Source remains ${source.branch}.`,
+    );
+    say(`Workflow ready at ${source.commit}.`);
+  }
+  if (saved.commit !== source.commit || saved.revision !== config.revision) {
+    saved = {
+      build: config.id,
+      commit: source.commit,
+      revision: config.revision,
+      idempotency: `cli-${randomUUID()}`,
+    };
+    await writePrivate(local, saved);
+  }
+  if (!saved.run) {
+    await confirm(
+      `Build committed source ${source.commit} using your Git provider`,
+      flags.yes,
+    );
+    const run = await api.call(
+      `/builds/${config.id}/run`,
+      { expected_config_revision: config.revision, commit: source.commit },
+      { idempotency: saved.idempotency },
+    );
+    saved.run = run.id;
+    await writePrivate(local, saved);
+  }
+  const base = `/builds/${config.id}/runs/${saved.run}`;
+  const run = await waitFor(
+    () => api.call(base),
+    (item) => ["completed", "failed", "cancelled"].includes(item.status),
+    "Build",
+  );
+  if (run.status !== "completed" || run.conclusion !== "success" || !run.image)
+    throw new Error(
+      `Build did not succeed. Inspect ${target}/builds/${config.id}. Fix it and push a new commit to start another build.`,
+    );
+  let deploymentID = run.deployment_id;
+  if (!deploymentID) {
+    const plan = await api.call(`${base}/plan`, {});
+    show(
+      `Review deployment\n${JSON.stringify({ image: run.image, changes: plan.changes, warnings: plan.warnings }, null, 2)}`,
+    );
+    await setupSecrets(api, config, plan);
+    await confirm("Deploy this built image", flags.yes);
+    const deployment = await api.call(`${base}/deploy`, {
+      expected_revision: plan.expected_revision,
+      expected_config_revision: plan.expected_config_revision,
+    });
+    deploymentID = deployment.id;
+  }
+  const deployment = await waitFor(
+    () => api.call(`/deployments/${deploymentID}`),
+    (item) =>
+      ["succeeded", "failed", "cancelled", "superseded"].includes(item.status),
+    "Deployment",
+  );
+  if (deployment.status !== "succeeded")
+    throw new Error(
+      `Deployment ${deployment.status}. Inspect ${target}/applications/${deployment.application_id} for diagnostics.`,
+    );
+  say(
+    `Deployment succeeded. ${target}/applications/${deployment.application_id}`,
+  );
+}
+main()
+  .catch((error) => {
+    if (error instanceof APIError && error.code === "approval_required") {
+      say(
+        "Deployment awaits a Cloud Team review. Open the workspace approvals in the dashboard; rerun deploy after approval.",
+      );
+    } else show(error.message || "The command could not finish.");
+    process.exitCode = 1;
+  })
+  .finally(() => rl?.close());