Rewrite tagoio init to follow clig.dev

.gitignore

@@ -61,3 +61,6 @@ exportBackup
 .tago-lock.dev-ue.lock
 .tago-lock.dev-ue-2.lock
 .tago-lock.dev-1.lock
+
+# generated by `npm run man` and shipped via the `files` field at publish time
+man/

README.md

@@ -51,6 +51,8 @@ Installing the TagoIO Command Line Tools is a straightforward process. Follow th
    tagoio login
    ```
 
+6. **Reference (Optional)**: A man page is installed alongside the CLI. Run `man tagoio` for the full command reference. Fish users can additionally run `fish_update_completions` to enable tab-completion (fish auto-extracts flag metadata from the installed man page).
+
 ## Command List
 List of commands of the CLI
 **Usage**:

package.json

@@ -20,10 +20,13 @@
     "npm": ">=10.0.0"
   },
   "files": [
-    "build"
+    "build",
+    "man"
   ],
   "scripts": {
-    "build": "rm -rf ./build; tsc --build; chmod +x ./build/index.js",
+    "man": "mkdir -p man && tsx src/lib/generate-man.ts > man/tagoio.1 && chmod 644 man/tagoio.1",
+    "build": "npm run man && rm -rf ./build; tsc --build; chmod +x ./build/index.js",
+    "prepublishOnly": "npm run man",
     "test": "vitest run",
     "test:single": "vitest --",
     "test:coverage": "vitest run --coverage",
@@ -35,6 +38,7 @@
   "bin": {
     "tagoio": "./build/index.js"
   },
+  "man": "./man/tagoio.1",
   "author": "TagoIO LLC",
   "license": "ISC",
   "dependencies": {
@@ -59,8 +63,8 @@
     "@types/prompts": "^2.4.9",
     "@types/unzipper": "^0.10.11",
     "@vitest/coverage-v8": "^4.1.5",
-    "oxfmt": "^0.46.0",
-    "oxlint": "1.61.0",
+    "oxfmt": "^0.47.0",
+    "oxlint": "1.62.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
   }

src/commands/analysis/analysis-console.test.ts

@@ -39,6 +39,16 @@ vi.mock("../../lib/messages.js", () => ({
   highlightMSG: (s: string) => s,
 }));
 
+vi.mock("../../lib/resolve-scope.js", () => ({
+  requireLocalScope: () => ({
+    scope: "local" as const,
+    root: "/repo",
+    configPath: "/repo/tagoconfig.json",
+    envFilePath: "/repo/.tagoio/personal.env",
+    configExists: true,
+  }),
+}));
+
 describe("connectAnalysisConsole", () => {
   const analysisList = [{ name: "script", fileName: "script.ts", id: "an-1" }];
 

src/commands/analysis/analysis-console.ts

@@ -2,6 +2,7 @@ import { Account, AnalysisInfo } from "@tago-io/sdk";
 import { EventSource } from "eventsource";
 import { getEnvironmentConfig, IEnvironment } from "../../lib/config-file.js";
 import { errorHandler, highlightMSG, infoMSG, successMSG } from "../../lib/messages.js";
+import { requireLocalScope } from "../../lib/resolve-scope.js";
 import { searchName } from "../../lib/search-name.js";
 import { pickAnalysisFromConfig } from "../../prompt/pick-analysis-from-config.js";
 
@@ -25,8 +26,8 @@ function apiSSE(profileToken: string, analysisID: string, urlSSERealtime?: strin
  * @param analysisList - The list of analysis objects to search through.
  * @returns The script object that matches the script name or the one selected by the user.
  */
-async function getScriptObj(scriptName: string | void, analysisList: IEnvironment["analysisList"]) {
-  let scriptObj: IEnvironment["analysisList"][0] | undefined;
+async function getScriptObj(scriptName: string | void, analysisList: NonNullable<IEnvironment["analysisList"]>) {
+  let scriptObj: NonNullable<IEnvironment["analysisList"]>[number] | undefined;
   if (scriptName) {
     scriptObj = searchName(
       scriptName,
@@ -69,12 +70,14 @@ function setupSSE(sse: ReturnType<typeof apiSSE>, _script_id: string, analysis_i
  * @returns void
  */
 async function connectAnalysisConsole(scriptName: string | void, options: { environment: string }) {
+  requireLocalScope("analysis-console");
+
   const config = getEnvironmentConfig(options.environment);
   if (!config || !config.profileToken) {
     errorHandler("Environment not found");
   }
 
-  const scriptObj = await getScriptObj(scriptName, config.analysisList);
+  const scriptObj = await getScriptObj(scriptName, config.analysisList ?? []);
   if (!scriptObj) {
     errorHandler(`Analysis not found: ${scriptName}`);
   }

src/commands/analysis/analysis-set-mode.test.ts

@@ -30,6 +30,16 @@ vi.mock("../../lib/messages.js", () => ({
   highlightMSG: (s: string) => s,
 }));
 
+vi.mock("../../lib/resolve-scope.js", () => ({
+  requireLocalScope: () => ({
+    scope: "local" as const,
+    root: "/repo",
+    configPath: "/repo/tagoconfig.json",
+    envFilePath: "/repo/.tagoio/personal.env",
+    configExists: true,
+  }),
+}));
+
 describe("analysisSetMode", () => {
   // Factory — the command sorts these in place, so each test needs a fresh copy.
   const makeAnalyses = () => [

src/commands/analysis/analysis-set-mode.ts

@@ -3,6 +3,7 @@ import kleur from "kleur";
 
 import { getEnvironmentConfig } from "../../lib/config-file.js";
 import { errorHandler, infoMSG, successMSG } from "../../lib/messages.js";
+import { requireLocalScope } from "../../lib/resolve-scope.js";
 import { chooseFromList } from "../../prompt/choose-from-list.js";
 import { pickFromList } from "../../prompt/pick-from-list.js";
 
@@ -62,6 +63,8 @@ async function chooseAnalysisToUpdateRunOnMode(
  * @param options.filterMode - The filter mode to use when retrieving the analysis list.
  */
 async function analysisSetMode(userInputName: string | void, options: { environment: string; mode: string; filterMode: string }) {
+  requireLocalScope("analysis-mode");
+
   const config = getEnvironmentConfig(options.environment);
   if (!config || !config.profileToken) {
     errorHandler("Environment not found");

src/commands/analysis/deploy.test.ts

@@ -46,8 +46,18 @@ vi.mock("../../lib/current-runtime.js", () => ({
   detectRuntime: detectRuntimeMock,
 }));
 
-vi.mock("../../lib/get-current-folder.js", () => ({
-  getCurrentFolder: () => "/repo",
+vi.mock("../../lib/resolve-scope.js", () => ({
+  requireLocalScope: () => ({
+    scope: "local" as const,
+    root: "/repo",
+    configPath: "/repo/tagoconfig.json",
+    envFilePath: "/repo/.tagoio/personal.env",
+    configExists: true,
+  }),
+}));
+
+vi.mock("../../lib/scope-notice.js", () => ({
+  printScopeBanner: vi.fn(),
 }));
 
 vi.mock("../../lib/messages.js", () => ({

src/commands/analysis/deploy.ts

@@ -5,8 +5,9 @@ import { Account, RunTypeOptions } from "@tago-io/sdk";
 
 import { getEnvironmentConfig, IConfigFile, IEnvironment } from "../../lib/config-file.js";
 import { detectRuntime } from "../../lib/current-runtime.js";
-import { getCurrentFolder } from "../../lib/get-current-folder.js";
 import { errorHandler, infoMSG, successMSG } from "../../lib/messages.js";
+import { requireLocalScope } from "../../lib/resolve-scope.js";
+import { printScopeBanner } from "../../lib/scope-notice.js";
 import { searchName } from "../../lib/search-name.js";
 import { chooseAnalysisListFromConfig } from "../../prompt/choose-analysis-list-config.js";
 import { confirmAnalysisFromConfig } from "../../prompt/confirm-analysis-list.js";
@@ -20,18 +21,19 @@ interface BuildScriptParams {
   config: EnvConfig;
   runtime: string;
   path: string;
+  /** Resolved local-scope project root. */
+  projectRoot: string;
 }
 
 /**
  * Returns an object containing the paths for analysis, build and current folder.
  * @param config - An object containing the configuration for the environment.
  * @returns An object containing the paths for analysis, build and current folder.
  */
-function getPaths(config: EnvConfig) {
-  const folderPath = getCurrentFolder();
+function getPaths(config: EnvConfig, projectRoot: string) {
   const buildPath = config.buildPath || `./build`;
   const analysisPath = config.analysisPath || `./src/analysis`;
-  return { analysisPath, buildPath, folderPath };
+  return { analysisPath, buildPath, folderPath: projectRoot };
 }
 
 /**
@@ -64,8 +66,8 @@ async function deleteOldFile(buildedFile: string) {
  * @param params - The parameters for building and uploading the script.
  */
 async function buildScript(params: BuildScriptParams) {
-  const { account, scriptName, analysisID, config, runtime, path } = params;
-  const { analysisPath, buildPath, folderPath } = getPaths(config);
+  const { account, scriptName, analysisID, config, runtime, path, projectRoot } = params;
+  const { analysisPath, buildPath, folderPath } = getPaths(config, projectRoot);
 
   let analysisFile;
   if (path) {
@@ -142,6 +144,10 @@ async function deployAnalysis(cmdScriptName: string, options: IDeployOptions) {
     errorHandler('Did you mean "tagoio deploy --all"? The "all" positional argument is no longer supported.');
   }
 
+  // Analysis development requires a project directory.
+  const scope = requireLocalScope("analysis-deploy");
+  printScopeBanner(scope, options.silent);
+
   const config = getEnvironmentConfig(options.environment);
   if (!config) {
     errorHandler("Environment not found");
@@ -155,12 +161,12 @@ async function deployAnalysis(cmdScriptName: string, options: IDeployOptions) {
   }
 
   // --all skips selection entirely; everything in analysisList with a fileName ships.
-  let scriptList = config.analysisList.filter((x) => x.fileName);
+  let scriptList = (config.analysisList ?? []).filter((x) => x.fileName);
   if (!options.all) {
     if (!cmdScriptName) {
       scriptList = await chooseAnalysisListFromConfig(scriptList);
     } else {
-      const analysisFound: IEnvironment["analysisList"][0] = searchName(
+      const analysisFound: NonNullable<IEnvironment["analysisList"]>[number] = searchName(
         cmdScriptName,
         scriptList.map((x) => ({ names: [x.name, x.fileName], value: x })),
       );
@@ -202,6 +208,7 @@ async function deployAnalysis(cmdScriptName: string, options: IDeployOptions) {
       config,
       runtime,
       path: path || "",
+      projectRoot: scope.root,
     });
   }
   process.exit();

src/commands/analysis/duplicate-analysis.test.ts

@@ -39,6 +39,16 @@ vi.mock("../../lib/messages.js", () => ({
   highlightMSG: (s: string) => s,
 }));
 
+vi.mock("../../lib/resolve-scope.js", () => ({
+  requireLocalScope: () => ({
+    scope: "local" as const,
+    root: "/repo",
+    configPath: "/repo/tagoconfig.json",
+    envFilePath: "/repo/.tagoio/personal.env",
+    configExists: true,
+  }),
+}));
+
 const pickAnalysisFromTagoIOMock = vi.fn();
 vi.mock("../../prompt/pick-analysis-from-tagoio.js", () => ({
   pickAnalysisFromTagoIO: (...args: unknown[]) => pickAnalysisFromTagoIOMock(...args),

src/commands/analysis/duplicate-analysis.ts

@@ -5,6 +5,7 @@ import zlib from "node:zlib";
 
 import { getEnvironmentConfig } from "../../lib/config-file.js";
 import { errorHandler, successMSG } from "../../lib/messages.js";
+import { requireLocalScope } from "../../lib/resolve-scope.js";
 import { pickAnalysisFromTagoIO } from "../../prompt/pick-analysis-from-tagoio.js";
 
 /**
@@ -78,6 +79,8 @@ async function downloadScriptBase64(account: Account, analysisId: string): Promi
  * @throws An error if the analysis ID is not found or if the environment is not found.
  */
 async function duplicateAnalysis(analysisID: string | void, options: { environment: string; name?: string }) {
+  requireLocalScope("analysis-duplicate");
+
   const config = getEnvironmentConfig(options.environment);
   if (!config || !config.profileToken) {
     errorHandler("Environment not found");

src/commands/analysis/run-analysis.test.ts

@@ -36,8 +36,14 @@ vi.mock("../../lib/current-runtime.js", () => ({
   detectRuntime: detectRuntimeMock,
 }));
 
-vi.mock("../../lib/get-current-folder.js", () => ({
-  getCurrentFolder: () => "/tmp/test",
+vi.mock("../../lib/resolve-scope.js", () => ({
+  requireLocalScope: () => ({
+    scope: "local" as const,
+    root: "/tmp/test",
+    configPath: "/tmp/test/tagoconfig.json",
+    envFilePath: "/tmp/test/.tagoio/personal.env",
+    configExists: true,
+  }),
 }));
 
 vi.mock("../../lib/messages.js", () => ({

src/commands/analysis/run-analysis.ts

@@ -5,8 +5,8 @@ import { Account } from "@tago-io/sdk";
 
 import { getEnvironmentConfig, IEnvironment, resolveCLIPath } from "../../lib/config-file.js";
 import { detectRuntime } from "../../lib/current-runtime.js";
-import { getCurrentFolder } from "../../lib/get-current-folder.js";
 import { errorHandler, highlightMSG, successMSG } from "../../lib/messages.js";
+import { requireLocalScope } from "../../lib/resolve-scope.js";
 import { searchName } from "../../lib/search-name.js";
 import { pickAnalysisFromConfig } from "../../prompt/pick-analysis-from-config.js";
 
@@ -68,13 +68,16 @@ async function runAnalysis(
   scriptName: string | undefined,
   options: { environment: string; debug: boolean; clear: boolean; tsnd: boolean; deno: boolean; node: boolean },
 ) {
+  // Analysis development requires a project directory.
+  const scope = requireLocalScope("analysis-run");
+
   const config = getEnvironmentConfig(options.environment);
   if (!config || !config.profileToken) {
     errorHandler("Environment not found");
   }
 
-  const analysisList = config.analysisList.filter((x) => x.fileName);
-  let scriptToRun: IEnvironment["analysisList"][0];
+  const analysisList = (config.analysisList ?? []).filter((x) => x.fileName);
+  let scriptToRun: NonNullable<IEnvironment["analysisList"]>[number];
   if (scriptName) {
     scriptName = scriptName.toLowerCase();
     scriptToRun = searchName(
@@ -111,7 +114,7 @@ async function runAnalysis(
 
   const spawnOptions: SpawnOptions = {
     shell: true,
-    cwd: getCurrentFolder(),
+    cwd: scope.root,
     stdio: "inherit",
     env: analysisEnv,
   };

src/commands/analysis/trigger-analysis.test.ts

@@ -31,6 +31,16 @@ vi.mock("../../lib/messages.js", () => ({
   highlightMSG: (s: string) => s,
 }));
 
+vi.mock("../../lib/resolve-scope.js", () => ({
+  requireLocalScope: () => ({
+    scope: "local" as const,
+    root: "/repo",
+    configPath: "/repo/tagoconfig.json",
+    envFilePath: "/repo/.tagoio/personal.env",
+    configExists: true,
+  }),
+}));
+
 describe("triggerAnalysis", () => {
   const analysisList = [
     { name: "myScript", fileName: "my-script.ts", id: "an-1" },

src/commands/analysis/trigger-analysis.ts

@@ -3,6 +3,7 @@ import kleur from "kleur";
 
 import { getEnvironmentConfig, IEnvironment } from "../../lib/config-file.js";
 import { errorHandler, infoMSG, successMSG } from "../../lib/messages.js";
+import { requireLocalScope } from "../../lib/resolve-scope.js";
 import { searchName } from "../../lib/search-name.js";
 import { pickAnalysisFromConfig } from "../../prompt/pick-analysis-from-config.js";
 import { pickAnalysisFromTagoIO } from "../../prompt/pick-analysis-from-tagoio.js";
@@ -16,16 +17,19 @@ import { pickAnalysisFromTagoIO } from "../../prompt/pick-analysis-from-tagoio.j
  * @param options.tago - Whether to pick the analysis from TagoIO.
  */
 async function triggerAnalysis(scriptName: string | void, options: { environment?: string; json?: string; tago: boolean }) {
+  requireLocalScope("analysis-trigger");
+
   const config = getEnvironmentConfig(options.environment);
 
   if (!config || !config.profileToken) {
     errorHandler("Environment not found");
   }
 
   const account = new Account({ token: config.profileToken, region: config.profileRegion });
-  const analysisList = config.analysisList.filter((x) => x.fileName);
+  const fullList = config.analysisList ?? [];
+  const analysisList = fullList.filter((x) => x.fileName);
 
-  let script: IEnvironment["analysisList"][0] | undefined;
+  let script: NonNullable<IEnvironment["analysisList"]>[number] | undefined;
 
   if (!scriptName && options.tago) {
     const analysis = await pickAnalysisFromTagoIO(account);
@@ -35,7 +39,7 @@ async function triggerAnalysis(scriptName: string | void, options: { environment
   } else {
     script = searchName(
       scriptName,
-      config.analysisList.map((x) => ({ names: [x.name, x.fileName], value: x })),
+      fullList.map((x) => ({ names: [x.name, x.fileName], value: x })),
     );
   }
 

src/commands/devices/change-bucket-type.ts

@@ -3,6 +3,8 @@ import kleur from "kleur";
 
 import { getEnvironmentConfig } from "../../lib/config-file.js";
 import { errorHandler, infoMSG, successMSG } from "../../lib/messages.js";
+import { resolveScope } from "../../lib/resolve-scope.js";
+import { printScopeBanner } from "../../lib/scope-notice.js";
 import { chooseFromList } from "../../prompt/choose-from-list.js";
 import { promptNumber } from "../../prompt/number-prompt.js";
 import { pickFromList } from "../../prompt/pick-from-list.js";
@@ -97,6 +99,8 @@ async function chooseBucketsFromList(account: Account) {
 }
 
 async function changeBucketType(id: string, options: { environment: string }) {
+  printScopeBanner(resolveScope());
+
   const config = getEnvironmentConfig(options.environment);
   if (!config || !config.profileToken) {
     errorHandler("Environment not found");