@astralos/cli 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +30 -0
  2. package/dist/astral.js +268 -20
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -40,6 +40,36 @@ Use `astral --help` or `astral <command> --help` for command details.
40
40
  names and flags. For example, `code.list_repos` becomes `astral code list-repos`.
41
41
  Group help includes catalog commands when you are signed in.
42
42
 
43
+ ## Code
44
+
45
+ `astral code` works on Astral repos and on GitHub repos that the workspace's
46
+ GitHub App grant reaches. It finds the repo from the git remote of the current
47
+ folder, or from `-R owner/repo`.
48
+
49
+ ```sh
50
+ astral code setup-git # plain git uses Astral for github.com
51
+ git clone https://github.com/owner/repo
52
+ astral code pr create --fill # GitHub: runs gh with a 1-hour token
53
+ astral code pr list
54
+ astral code repo view owner/repo
55
+ astral code repo clone my-astral-repo
56
+ astral code repo view my-astral-repo
57
+ ```
58
+
59
+ For a GitHub repo, `astral code pr|repo|issue|run|search|api|release|workflow|label|browse`
60
+ runs the real `gh` with your arguments unchanged. The CLI gets a GitHub token for
61
+ that one repo, and only the `gh` process sees it (`GH_TOKEN`). The token ends
62
+ after 1 hour and is never printed or saved. Push access needs manage access to
63
+ the repo; read commands use a read-only token. A token never reaches more than
64
+ one repo: `astral code search` needs `--repo owner/repo`, and
65
+ `astral code list-repos` lists the workspace repos instead of `repo list`.
66
+
67
+ For an Astral repo, `repo clone` and `repo view` work. Astral repos have no pull
68
+ requests. Use `astral code clone`, `astral code push`, or plain git.
69
+
70
+ `astral code setup-git` makes git ask `astral code credential` for github.com.
71
+ Plain `git clone`, `fetch`, and `push` then use the same one-repo token.
72
+
43
73
  ## Agent instructions
44
74
 
45
75
  `astral agent-setup` prints a marked AGENTS.md snippet. It needs no sign-in.
package/dist/astral.js CHANGED
@@ -10246,6 +10246,14 @@ var EXIT_FOR_ERROR = {
10246
10246
  };
10247
10247
  var exitCodeFor = (type) => EXIT_FOR_ERROR[type] ?? EXIT.failure;
10248
10248
 
10249
+ class CommandExit extends Error {
10250
+ exitCode;
10251
+ constructor(exitCode) {
10252
+ super(`Command exited with ${exitCode}.`);
10253
+ this.exitCode = exitCode;
10254
+ }
10255
+ }
10256
+
10249
10257
  class CliError extends Error {
10250
10258
  error;
10251
10259
  constructor(error) {
@@ -10267,7 +10275,7 @@ var ASTRAL_APPROVAL_HEADER = "Astral-Approval";
10267
10275
  // package.json
10268
10276
  var package_default = {
10269
10277
  name: "@astralos/cli",
10270
- version: "0.1.4",
10278
+ version: "0.1.5",
10271
10279
  license: "MIT",
10272
10280
  description: "The Astral command line. Every Astral tool, from a terminal or an agent.",
10273
10281
  publishConfig: {
@@ -10885,6 +10893,22 @@ var parseCredentialRequest = (text) => {
10885
10893
  return fields;
10886
10894
  };
10887
10895
 
10896
+ // src/github.ts
10897
+ var CREDENTIAL_TOOLS = new Set(["code.github_read_token", "code.github_write_token"]);
10898
+ var githubRepo = (value) => {
10899
+ const match = value.match(/^(?:https?:\/\/github\.com\/|ssh:\/\/(?:git@)?github\.com\/|git@github\.com:)?([^/\s:]+)\/([^/\s?#]+)\/?$/i);
10900
+ return match ? `${match[1]}/${match[2].replace(/\.git$/i, "")}` : null;
10901
+ };
10902
+ var githubCredentials = async (params) => {
10903
+ const { client, read, repo } = params;
10904
+ const { credentials } = await client.call({
10905
+ method: "POST",
10906
+ path: `/api/v1/tools/code.github_${read ? "read" : "write"}_token`,
10907
+ json: { repo }
10908
+ });
10909
+ return credentials;
10910
+ };
10911
+
10888
10912
  // src/commands/code-git.ts
10889
10913
  var depsOf = (runtime) => ({
10890
10914
  git: runtime.git ?? runGit,
@@ -10947,29 +10971,33 @@ var credentialEnv = (credentials) => ({
10947
10971
  [URL_ENV]: credentials.url,
10948
10972
  GIT_TERMINAL_PROMPT: "0"
10949
10973
  });
10974
+ var cloneRepo = async (params) => {
10975
+ const { runtime, globals, ref, dir } = params;
10976
+ const deps = depsOf(runtime);
10977
+ const client = clientFor(runtime, globals);
10978
+ const repo = await resolveRepo(client, ref);
10979
+ const credentials = await readCredentials(client, repo.id);
10980
+ const target = dir ?? (repo.name === repo.id ? repo.id : repo.name);
10981
+ const config = cloneConfig({ url: credentials.url, repoId: repo.id, profile: client.context.profile, self: deps.self() });
10982
+ const result = await deps.git({
10983
+ args: ["clone", ...config, credentials.url, target],
10984
+ env: { ...runtime.env, ...credentialEnv(credentials) },
10985
+ stdio: "inherit"
10986
+ });
10987
+ if (result.status !== 0)
10988
+ throw cliError("upstream_error", `git clone exited with ${result.status}.`, { git_exit: result.status });
10989
+ emit({
10990
+ runtime,
10991
+ globals,
10992
+ data: { repo_id: repo.id, dir: target, url: credentials.url, default_branch: credentials.default_branch },
10993
+ human: (data) => `Cloned ${repo.name} into ${data.dir}. \`astral code push\` pushes to it.`
10994
+ });
10995
+ };
10950
10996
  var registerCodeGit = (program, runtime) => {
10951
10997
  const deps = depsOf(runtime);
10952
10998
  const code = program.commands.find((command) => command.name() === "code") ?? program.command("code").description("Astral repos: clone, push, and the code tools");
10953
10999
  code.command("clone <repo> [dir]").description("clone an Astral repo (id or name) and set up git credentials for it").action(async (ref, dir, _options, command) => {
10954
- const globals = globalsOf(command);
10955
- const client = clientFor(runtime, globals);
10956
- const repo = await resolveRepo(client, ref);
10957
- const credentials = await readCredentials(client, repo.id);
10958
- const target = dir ?? (repo.name === repo.id ? repo.id : repo.name);
10959
- const config = cloneConfig({ url: credentials.url, repoId: repo.id, profile: client.context.profile, self: deps.self() });
10960
- const result = await deps.git({
10961
- args: ["clone", ...config, credentials.url, target],
10962
- env: { ...runtime.env, ...credentialEnv(credentials) },
10963
- stdio: "inherit"
10964
- });
10965
- if (result.status !== 0)
10966
- throw cliError("upstream_error", `git clone exited with ${result.status}.`, { git_exit: result.status });
10967
- emit({
10968
- runtime,
10969
- globals,
10970
- data: { repo_id: repo.id, dir: target, url: credentials.url, default_branch: credentials.default_branch },
10971
- human: (data) => `Cloned ${repo.name} into ${data.dir}. \`astral code push\` pushes to it.`
10972
- });
11000
+ await cloneRepo({ runtime, globals: globalsOf(command), ref, dir });
10973
11001
  });
10974
11002
  code.command("push [git-args...]").description("push to the Astral repo of this clone; args go to git push").allowUnknownOption().option("--repo <id>", "the repo id (default: git config astral.repoId)").option("--no-wait", "if a call needs approval, exit 10 with the link instead of waiting").action(async (args, options, command) => {
10975
11003
  const globals = globalsOf(command);
@@ -10994,11 +11022,52 @@ var registerCodeGit = (program, runtime) => {
10994
11022
  throw cliError("upstream_error", `git push exited with ${result.status}.`, { git_exit: result.status });
10995
11023
  emit({ runtime, globals, data: { repo_id: repoId, pushed: true }, human: () => "Pushed." });
10996
11024
  });
11025
+ code.command("setup-git").description("set up the GitHub credential helper for plain git").action(async (_options, command) => {
11026
+ const globals = globalsOf(command);
11027
+ const profile = globals.profile ? ["--profile", globals.profile] : [];
11028
+ const helper = `!${[...deps.self(), ...profile, "code", "credential"].map(shellQuote).join(" ")}`;
11029
+ const key = "credential.https://github.com.helper";
11030
+ for (const args of [
11031
+ ["config", "--global", "--replace-all", key, ""],
11032
+ ["config", "--global", "--add", key, helper],
11033
+ ["config", "--global", "--replace-all", "credential.https://github.com.useHttpPath", "true"]
11034
+ ]) {
11035
+ const result = await deps.git({ args, stdio: "pipe" });
11036
+ if (result.status !== 0)
11037
+ throw cliError("upstream_error", `git config exited with ${result.status}.`);
11038
+ }
11039
+ emit({ runtime, globals, data: { helper, useHttpPath: true }, human: () => `Set ${key} to an empty helper, then ${helper}.
11040
+ Set credential.https://github.com.useHttpPath=true.` });
11041
+ });
10997
11042
  code.command("credential <operation>").description("git credential helper (git runs it; you do not)").option("--repo <id>", "the repo id").action(async (operation, options, command) => {
10998
11043
  if (operation !== "get")
10999
11044
  return;
11000
11045
  const request = parseCredentialRequest(await deps.readStdin());
11001
11046
  const globals = globalsOf(command);
11047
+ if (!options.repo && !Object.entries(runtime.env).some(([key, value]) => key.startsWith("ASTRAL_GIT_") && value !== undefined)) {
11048
+ if (request.protocol !== "https" || request.host?.toLowerCase() !== "github.com" || !request.path)
11049
+ return;
11050
+ const repo = githubRepo(request.path);
11051
+ if (!repo)
11052
+ return;
11053
+ const client = clientFor(runtime, globals);
11054
+ let credentials;
11055
+ try {
11056
+ credentials = await githubCredentials({ client, read: false, repo });
11057
+ } catch (error) {
11058
+ if (!(error instanceof CliError) || error.error.type !== "permission_denied")
11059
+ throw error;
11060
+ credentials = await githubCredentials({ client, read: true, repo });
11061
+ }
11062
+ const lines = ["username=x-access-token", `password=${credentials.token}`];
11063
+ const expiry = Date.parse(credentials.expires_at);
11064
+ if (Number.isFinite(expiry))
11065
+ lines.push(`password_expiry_utc=${Math.floor(expiry / 1000)}`);
11066
+ runtime.stdout(`${lines.join(`
11067
+ `)}
11068
+ `);
11069
+ return;
11070
+ }
11002
11071
  const credentials = await helperCredentials(runtime, globals, options.repo);
11003
11072
  if (!credentials || !matchesRemote(request, credentials.url))
11004
11073
  return;
@@ -11023,6 +11092,173 @@ var helperCredentials = async (runtime, globals, repoId) => {
11023
11092
  return readCredentials(clientFor(runtime, globals), repoId);
11024
11093
  };
11025
11094
 
11095
+ // src/gh.ts
11096
+ import { spawn as spawn2 } from "node:child_process";
11097
+ var runGh = ({ args, env, stdio }) => new Promise((resolve, reject) => {
11098
+ const child = spawn2("gh", args, { env: { ...process.env, ...env }, stdio });
11099
+ child.on("error", (error) => {
11100
+ reject(cliError("upstream_error", error.code === "ENOENT" ? "The gh binary is missing. Install GitHub CLI to use this command." : "Could not start gh."));
11101
+ });
11102
+ child.on("close", (code) => resolve(code ?? 1));
11103
+ });
11104
+
11105
+ // src/commands/code-gh.ts
11106
+ var GH_COMMANDS = ["pr", "repo", "issue", "run", "search", "api", "release", "workflow", "label", "browse"];
11107
+ var flagValues = (args, names) => {
11108
+ const values = [];
11109
+ for (let index = 0;index < args.length; index++) {
11110
+ const arg = args[index];
11111
+ if (arg === "--")
11112
+ break;
11113
+ for (const name of names) {
11114
+ if (arg === name && args[index + 1])
11115
+ values.push(args[index + 1]);
11116
+ else if (name.startsWith("--") && arg.startsWith(`${name}=`))
11117
+ values.push(arg.slice(name.length + 1));
11118
+ else if (!name.startsWith("--") && arg.startsWith(name) && arg.length > name.length)
11119
+ values.push(arg.slice(name.length));
11120
+ }
11121
+ }
11122
+ return values;
11123
+ };
11124
+ var flag = (args, names) => flagValues(args, names)[0];
11125
+ var repoPositionals = (args) => {
11126
+ const values = [];
11127
+ const options = ["-R", "--repo", "--owner", "--json", "--jq", "-q", "--template", "-t", "--limit", "-L"];
11128
+ for (let index = 2;index < args.length; index++) {
11129
+ const arg = args[index];
11130
+ if (arg === "--")
11131
+ break;
11132
+ if (options.includes(arg))
11133
+ index++;
11134
+ else if (!arg.startsWith("-"))
11135
+ values.push(arg);
11136
+ }
11137
+ return values;
11138
+ };
11139
+ var urlRepo = (args) => {
11140
+ const endpoint = args[0] === "api" ? args[1]?.match(/^\/?repos\/([^/{}]+)\/([^/?#{}]+)/) : null;
11141
+ if (endpoint)
11142
+ return `${endpoint[1]}/${endpoint[2]}`;
11143
+ for (const arg of repoPositionals(args)) {
11144
+ const match = arg.match(/^https?:\/\/(?:www\.)?github\.com\/([^/]+)\/([^/?#]+)/i);
11145
+ if (match)
11146
+ return `${match[1]}/${match[2].replace(/\.git$/i, "")}`;
11147
+ }
11148
+ return null;
11149
+ };
11150
+ var detectRepo = async (params) => {
11151
+ const { args, runtime } = params;
11152
+ const explicit = flag(args, ["-R", "--repo"]);
11153
+ if (explicit)
11154
+ return explicit;
11155
+ if (args[0] === "repo" && ["view", "clone"].includes(args[1] ?? "")) {
11156
+ const positional = repoPositionals(args)[0];
11157
+ if (positional)
11158
+ return positional;
11159
+ }
11160
+ const url = urlRepo(args);
11161
+ if (url)
11162
+ return url;
11163
+ const envRepo = runtime.env.GH_REPO?.trim().replace(/^github\.com\//i, "");
11164
+ if (envRepo)
11165
+ return envRepo;
11166
+ const git = runtime.git ?? runGit;
11167
+ const config = await git({ args: ["config", "--get", "astral.repoId"], stdio: "pipe" });
11168
+ if (config.status === 0 && config.stdout.trim())
11169
+ return config.stdout.trim();
11170
+ let remote = await git({ args: ["remote", "get-url", "origin"], stdio: "pipe" });
11171
+ if (remote.status !== 0 || !remote.stdout.trim()) {
11172
+ const remotes = await git({ args: ["remote"], stdio: "pipe" });
11173
+ const first = remotes.stdout.trim().split(`
11174
+ `)[0];
11175
+ if (remotes.status !== 0 || !first)
11176
+ return null;
11177
+ remote = await git({ args: ["remote", "get-url", first], stdio: "pipe" });
11178
+ }
11179
+ if (remote.status !== 0 || !/^(?:https?:\/\/github\.com\/|ssh:\/\/(?:git@)?github\.com\/|git@github\.com:)/i.test(remote.stdout.trim()))
11180
+ return null;
11181
+ return githubRepo(remote.stdout.trim());
11182
+ };
11183
+ var isReadCommand = (args) => {
11184
+ const [command, action] = args;
11185
+ if (command === "browse" || command === "search")
11186
+ return true;
11187
+ if (command === "api") {
11188
+ if (flagValues(args, ["-X", "--method"]).some((method) => method.toUpperCase() !== "GET"))
11189
+ return false;
11190
+ return !args.some((arg) => /^(?:-[fF].*|--(?:field|raw-field|input)(?:=|$))/.test(arg));
11191
+ }
11192
+ const reads = {
11193
+ pr: ["list", "view", "diff", "checks", "status"],
11194
+ issue: ["list", "view", "status"],
11195
+ repo: ["view", "clone", "list"],
11196
+ run: ["list", "view", "watch", "download"],
11197
+ release: ["list", "view", "download"],
11198
+ workflow: ["list", "view"],
11199
+ label: ["list"]
11200
+ };
11201
+ return reads[command ?? ""]?.includes(action ?? "") ?? false;
11202
+ };
11203
+ var astralCommand = async (params) => {
11204
+ const { args, ref, runtime, command } = params;
11205
+ const globals = globalsOf(command);
11206
+ if (args[0] === "repo" && args[1] === "clone") {
11207
+ const positionals = repoPositionals(args);
11208
+ const dir = positionals[flag(args, ["-R", "--repo"]) ? 0 : 1];
11209
+ await cloneRepo({ runtime, globals: { ...globals, json: globals.json || args.includes("--json") }, ref, dir });
11210
+ return;
11211
+ }
11212
+ if (args[0] === "repo" && args[1] === "view") {
11213
+ const client = clientFor(runtime, globals);
11214
+ const repo = await resolveRepo(client, ref);
11215
+ const data = await client.call({ method: "POST", path: "/api/v1/tools/code.get_repo", json: { id: repo.id } });
11216
+ emit({
11217
+ runtime,
11218
+ globals: { ...globals, json: globals.json || args.includes("--json") },
11219
+ data,
11220
+ human: ({ repo: detail }) => [
11221
+ `Name: ${detail.name}`,
11222
+ `Kind: ${detail.kind}`,
11223
+ `Default branch: ${detail.default_branch}`,
11224
+ `Description: ${detail.description ?? "-"}`,
11225
+ `URL: ${detail.html_url ?? "-"}`
11226
+ ].join(`
11227
+ `)
11228
+ });
11229
+ return;
11230
+ }
11231
+ throw cliError("invalid_input", "Astral repos do not support this command. Supported commands: astral code repo clone, astral code repo view, astral code clone, astral code push, and plain git with the credential helper. Astral repos have no pull requests.");
11232
+ };
11233
+ var registerCodeGh = (program, runtime) => {
11234
+ const code = program.commands.find((command) => command.name() === "code");
11235
+ code.enablePositionalOptions();
11236
+ for (const name of GH_COMMANDS) {
11237
+ code.command(`${name} [args...]`).description(`${name} for GitHub repos (args go to gh)`).allowUnknownOption().passThroughOptions().helpOption(false).action(async (_args, _options, command) => {
11238
+ const args = [...code.args];
11239
+ const globals = globalsOf(command);
11240
+ if (name === "repo" && args[1] === "list") {
11241
+ throw cliError("invalid_input", "A GitHub token here reaches one repo. List the workspace repos with astral code list-repos.");
11242
+ }
11243
+ if (name === "search" && !flag(args, ["-R", "--repo"])) {
11244
+ throw cliError("invalid_input", "A GitHub token here reaches one repo. Name it with --repo owner/repo.");
11245
+ }
11246
+ const ref = await detectRepo({ args, runtime });
11247
+ if (!ref)
11248
+ throw cliError("invalid_input", "Run this in a clone, or name the repo with -R owner/repo.");
11249
+ const repo = githubRepo(ref);
11250
+ if (ref.includes("/") && !repo)
11251
+ throw cliError("invalid_input", "Use a GitHub repo in the form owner/repo or a github.com URL.");
11252
+ if (!repo)
11253
+ return astralCommand({ args, ref, runtime, command });
11254
+ const credentials = await githubCredentials({ client: clientFor(runtime, globals), read: isReadCommand(args), repo });
11255
+ const status = await (runtime.gh ?? runGh)({ args, env: { ...process.env, ...runtime.env, GH_REPO: repo, GH_TOKEN: credentials.token }, stdio: "inherit" });
11256
+ if (status !== 0)
11257
+ throw new CommandExit(status);
11258
+ });
11259
+ }
11260
+ };
11261
+
11026
11262
  // src/catalog.ts
11027
11263
  import { createHash } from "node:crypto";
11028
11264
  import { mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
@@ -11133,6 +11369,8 @@ var registerCall = (parent, runtime) => {
11133
11369
  parent.command("call <app.tool>").description("call a tool with JSON input").option("--input <json>", "input as a JSON object").option("--input-file <path>", "read JSON from a file, or - for stdin").action(async (name, options, command) => {
11134
11370
  if (!/^[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+$/.test(name))
11135
11371
  throw cliError("invalid_input", "Use a tool name in app.tool form.");
11372
+ if (CREDENTIAL_TOOLS.has(name))
11373
+ throw cliError("invalid_input", `${name} returns a raw token, so it cannot be called here. Use astral code gh commands or plain git with the credential helper.`);
11136
11374
  const globals = globalsOf(command);
11137
11375
  const data = await callWithApproval({
11138
11376
  client: clientFor(runtime, globals),
@@ -11236,6 +11474,8 @@ var registerTool = (command, tool, runtime) => {
11236
11474
  var findCommand = (program, name) => program.commands.find((command) => command.name() === name || command.aliases().includes(name));
11237
11475
  var addGeneratedCommands = (program, runtime, catalog) => {
11238
11476
  for (const tool of catalog.tools) {
11477
+ if (CREDENTIAL_TOOLS.has(tool.name))
11478
+ continue;
11239
11479
  let app = findCommand(program, tool.app);
11240
11480
  if (app && app.commands.length === 0)
11241
11481
  continue;
@@ -19580,6 +19820,8 @@ class StdioServerTransport {
19580
19820
  var mcpToolMap = (tools) => {
19581
19821
  const mapped = new Map;
19582
19822
  for (const tool of tools) {
19823
+ if (CREDENTIAL_TOOLS.has(tool.name))
19824
+ continue;
19583
19825
  const base = `${tool.app}__${tool.tool}`;
19584
19826
  let name = base;
19585
19827
  if (!/^[a-zA-Z0-9_-]{1,64}$/.test(name) || mapped.has(name)) {
@@ -19952,6 +20194,7 @@ var buildProgram = async (runtime) => {
19952
20194
  registerMcp(program, runtime);
19953
20195
  registerWorkspace(program, runtime);
19954
20196
  registerCodeGit(program, runtime);
20197
+ registerCodeGh(program, runtime);
19955
20198
  registerTools(program, runtime);
19956
20199
  registerProject(program, runtime);
19957
20200
  registerSitesLogs(program, runtime);
@@ -19962,6 +20205,9 @@ var run = async (argv, runtime) => {
19962
20205
  let errorRuntime = runtime;
19963
20206
  try {
19964
20207
  const program = await buildProgram(runtime);
20208
+ program.enablePositionalOptions();
20209
+ const { operands, unknown } = program.parseOptions(argv);
20210
+ program.enablePositionalOptions(operands[0] === "code" && GH_COMMANDS.includes(unknown[0] ?? ""));
19965
20211
  program.hook("preAction", (_command, action) => {
19966
20212
  if (action.name() === "mcp")
19967
20213
  errorRuntime = { ...runtime, stdout: runtime.stderr };
@@ -19970,6 +20216,8 @@ var run = async (argv, runtime) => {
19970
20216
  await program.parseAsync(argv, { from: "user" });
19971
20217
  return EXIT.ok;
19972
20218
  } catch (error) {
20219
+ if (error instanceof CommandExit)
20220
+ return error.exitCode;
19973
20221
  if (error instanceof CommanderError) {
19974
20222
  return error.exitCode === 0 ? EXIT.ok : EXIT.invalid_input;
19975
20223
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astralos/cli",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "license": "MIT",
5
5
  "description": "The Astral command line. Every Astral tool, from a terminal or an agent.",
6
6
  "publishConfig": {