subto 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# Subto CLI
+
+This folder contains the Subto command-line client which is a thin wrapper around the Subto.One API.
+
+Installation
+
+- Global (recommended via npm):
+
+```bash
+npm install -g subto-cli
+```
+
+- Or run locally from the `cli` folder during development:
+
+```bash
+cd cli
+npm install
+node bin/subto.js --help
+```
+
+Local testing (before publishing)
+
+- Link the package locally and test the installed command:
+
+```bash
+cd cli
+npm link
+subto --help
+```
+
+Commands
+
+- `subto login`
+  - Prompts for your API key and stores it in `~/.subto/config.json`.
+
+- `subto scan <url>`
+  - Requests a scan for `<url>` from the Subto API. Example body:
+
+```json
+{
+  "url": "https://example.com",
+  "source": "cli",
+  "client": { "name": "subto-cli", "version": "0.1.0" }
+}
+```
+
+Notes
+
+- The CLI calls the remote API and respects server-side rate limiting. If a rate limit is encountered the CLI prints a friendly message like:
+
+```
+Rate limit reached. Try again in X seconds.
+```
+
+- The API key is stored at `~/.subto/config.json` with restrictive permissions (0600).
+- The CLI never logs or prints API keys or other secrets.
+- The CLI never performs website scanning locally — it only calls the remote API.
+
+- `--wait` flag: block and poll until the scan completes
+
+Example:
+
+```bash
+subto scan https://example.com --wait
+```
+
+This will poll the server every 5 seconds (respecting `Retry-After`) and display queue position, progress percentage and stages as provided by the API, then print the full JSON result when finished.
+
+Default behavior
+
+- By default the CLI will automatically poll when the server immediately returns a queued/started response. If you prefer to return immediately, use `--no-wait`.
+
+Example (do not wait):
+
+```bash
+subto scan https://example.com --no-wait
+```
+
+Publishing the CLI
+
+Exact steps to publish (do not run automatically):
+
+```bash
+npm login
+npm publish
+```
+
+Pre-publish check
+
+The package runs a `prepublishOnly` script which verifies `bin/subto.js` exists and that the `bin` mapping is correct. The script also attempts to set the executable bit on the entry file.
+
+API docs section (link)
+
+See the bundled API docs excerpt for the Subto CLI in `./docs/cli-section.md`.
+
+Download
+
+After publishing or packing, a distributable tarball will be available under `./dist/` e.g.:
+
+```
+./dist/subto-0.1.0.tgz
+```
+
+You can download that file directly and install locally with:
+
+```bash
+npm install -g ./dist/subto-0.1.0.tgz
+```

package/bin/subto.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/* Entrypoint for the `subto` CLI. Delegates to ../index.js */
+const path = require('path');
+const cli = require(path.join(__dirname, '..', 'index.js'));
+if (require.main === module) {
+  cli.run(process.argv.slice(2)).catch(err => {
+    console.error(err.message ? String(err.message) : String(err));
+    process.exit(1);
+  });
+}

package/docs/cli-section.md

@@ -0,0 +1,27 @@
+## Subto CLI
+
+Installation
+
+- Install via npm:
+
+```
+npm install -g subto-cli
+```
+
+Commands
+
+- `subto login`
+  - Prompts for your API key and stores it in `~/.subto/config.json`.
+
+- `subto scan <url>`
+  - Requests a scan for `<url>` from the Subto API.
+
+Notes
+
+- The CLI calls the remote API and respects server-side rate limiting. If a rate limit is encountered the CLI prints a friendly message like:
+
+```
+Rate limit reached. Try again in X seconds.
+```
+
+- For more information and installation help see `/cli/README.md` in this repository.

package/index.js

@@ -0,0 +1,202 @@
+/* Subto CLI implementation */
+const { Command } = require('commander');
+const fs = require('fs').promises;
+const os = require('os');
+const path = require('path');
+const readline = require('readline');
+// Chalk v5 is ESM — when required from CommonJS it may expose a default export.
+const _chalk = require('chalk');
+const chalk = (_chalk && _chalk.default) ? _chalk.default : _chalk;
+
+const CONFIG_DIR = path.join(os.homedir(), '.subto');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+const DEFAULT_API_BASE = 'https://subto.one';
+const CLIENT_META = { name: 'subto-cli', version: '0.1.0' };
+
+function configFilePath() { return CONFIG_PATH; }
+
+async function readConfig() {
+  try {
+    const content = await fs.readFile(configFilePath(), 'utf8');
+    return JSON.parse(content);
+  } catch (err) { return null; }
+}
+
+async function writeConfig(obj) {
+  await fs.mkdir(CONFIG_DIR, { mode: 0o700, recursive: true });
+  const data = JSON.stringify(obj, null, 2);
+  const tmp = configFilePath() + '.tmp';
+  await fs.writeFile(tmp, data, { mode: 0o600 });
+  await fs.rename(tmp, configFilePath());
+}
+
+async function promptHidden(prompt) {
+  if (!process.stdin.isTTY) throw new Error('Interactive prompt required');
+  return new Promise((resolve, reject) => {
+    const stdin = process.stdin;
+    stdin.resume();
+    stdin.setRawMode(true);
+    let value = '';
+    process.stdout.write(prompt);
+    function onData(char) {
+      char = String(char);
+      const code = char.charCodeAt(0);
+      if (code === 13 || code === 10) {
+        stdin.removeListener('data', onData);
+        stdin.setRawMode(false);
+        process.stdout.write('\n');
+        resolve(value.trim());
+        return;
+      }
+      if (code === 3) {
+        stdin.removeListener('data', onData);
+        stdin.setRawMode(false);
+        reject(new Error('Aborted'));
+        return;
+      }
+      if (code === 127 || code === 8) { value = value.slice(0, -1); process.stdout.clearLine(); process.stdout.cursorTo(0); process.stdout.write(prompt + '*'.repeat(value.length)); return; }
+      value += char; process.stdout.write('*');
+    }
+    stdin.on('data', onData);
+  });
+}
+
+function validateUrl(input) {
+  try { const u = new URL(input); if (u.protocol !== 'http:' && u.protocol !== 'https:') return false; return true; } catch (err) { return false; }
+}
+
+async function postScan(url, apiKey) {
+  const base = process.env.SUBTO_API_BASE_URL || DEFAULT_API_BASE;
+  const endpoint = new URL('/api/v1/scan', base).toString();
+  const body = { url, source: 'cli', client: CLIENT_META };
+  const fetchFn = global.fetch;
+  if (typeof fetchFn !== 'function') throw new Error('Global fetch() is not available in this Node runtime. Use Node 18+');
+  const res = await fetchFn(endpoint, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}`, 'User-Agent': `${CLIENT_META.name}/${CLIENT_META.version}` }, body: JSON.stringify(body) });
+  const text = await res.text();
+  let data = null; try { data = text ? JSON.parse(text) : null; } catch (e) { data = text; }
+  return { status: res.status, headers: res.headers, body: data };
+}
+
+function printScanSummary(obj) {
+  if (!obj || typeof obj !== 'object') { console.log(obj); return; }
+  console.log(chalk.bold('Scan result:'));
+  if (obj.id) console.log(chalk.green('  ID:') + ' ' + obj.id);
+  if (obj.url) console.log(chalk.green('  URL:') + ' ' + obj.url);
+  if (obj.status) console.log(chalk.green('  Status:') + ' ' + obj.status);
+  if (obj.createdAt) console.log(chalk.green('  Created:') + ' ' + obj.createdAt);
+  if (obj.summary) console.log(chalk.green('  Summary:') + ' ' + obj.summary);
+  const keys = Object.keys(obj).filter(k => !['id','url','status','createdAt','summary'].includes(k));
+  if (keys.length) console.log(chalk.dim('  Additional keys: ' + keys.join(', ')));
+}
+
+async function run(argv) {
+  const program = new Command();
+  program.name('subto').description('Subto CLI — wrapper around Subto.One API').version('0.1.0');
+
+  program.command('login').description('Store your API key in ~/.subto/config.json').action(async () => {
+    try {
+      const apiKey = await promptHidden('API key: ');
+      if (!apiKey || !apiKey.trim()) throw new Error('No API key entered. Aborting.');
+      if (apiKey.length < 10) throw new Error('API key looks too short.');
+      await writeConfig({ apiKey: apiKey.trim() });
+      console.log(chalk.green('API key saved to'), chalk.cyan(configFilePath()));
+    } catch (err) { if (err && err.message === 'Aborted') { console.log('\n' + chalk.yellow('Login aborted.')); process.exit(1); } throw err; }
+  });
+
+  program
+    .command('scan <url>')
+    .description('Request a scan for <url> via the Subto API')
+    .option('--json', 'Output raw JSON')
+    .option('--wait', 'Poll for completion and show progress')
+    .option('--no-wait', 'Do not poll; return immediately')
+    .action(async (url, opts) => {
+      if (!validateUrl(url)) { console.error(chalk.red('Invalid URL. Provide a full URL including http:// or https://')); process.exit(1); }
+      const cfg = await readConfig(); if (!cfg || !cfg.apiKey) { console.error(chalk.red('Missing API key. Run:'), chalk.cyan('subto login')); process.exit(1); }
+      try {
+        const resp = await postScan(url, cfg.apiKey);
+        if (resp.status === 429) {
+          let retrySeconds = null;
+          if (resp.body && typeof resp.body === 'object' && resp.body.retry_after) retrySeconds = resp.body.retry_after;
+          try { const ra = resp.headers.get && resp.headers.get('retry-after'); if (!retrySeconds && ra) retrySeconds = parseInt(ra, 10); } catch (e) {}
+          if (retrySeconds) console.error(chalk.yellow(`Rate limit reached. Try again in ${retrySeconds} seconds.`)); else console.error(chalk.yellow('Rate limit reached. Try again later.'));
+          process.exit(1);
+        }
+        if (resp.status < 200 || resp.status >= 300) { let msg = `Request failed with status ${resp.status}`; if (resp.body && typeof resp.body === 'object' && resp.body.error) msg += ': ' + resp.body.error; console.error(chalk.red(msg)); process.exit(1); }
+
+        // Decide whether to poll:
+        // - if user passed --wait -> poll
+        // - if user passed --no-wait -> do not poll
+        // - otherwise, poll by default when server returns a queued/started status
+        const serverStatus = resp.body && resp.body.status;
+        const serverIndicatesQueued = serverStatus && ['started', 'queued', 'pending', 'accepted'].includes(String(serverStatus).toLowerCase());
+        const shouldPoll = (!opts.noWait) && (opts.wait || serverIndicatesQueued);
+
+        // If user asked for JSON only and we're not polling, print and exit.
+        if (opts.json && !shouldPoll) {
+          console.log(JSON.stringify(resp.body, null, 2));
+          return;
+        }
+
+        // If we should poll, poll the scan resource until completion and print progress.
+        if (shouldPoll) {
+          const scanId = (resp.body && (resp.body.scanId || resp.body.id || resp.body.scan_id));
+          if (!scanId) {
+            console.error(chalk.red('Server did not return a scanId to poll.'));
+            process.exit(1);
+          }
+
+          const base = process.env.SUBTO_API_BASE_URL || DEFAULT_API_BASE;
+          const fetchFn = global.fetch;
+          if (typeof fetchFn !== 'function') throw new Error('Global fetch() is not available in this Node runtime. Use Node 18+');
+
+          const sleep = ms => new Promise(r => setTimeout(r, ms));
+          let interval = 5000;
+          console.log(chalk.blue('Queued scan. Polling for progress...'));
+
+          while (true) {
+            const statusUrl = new URL(`/api/v1/scan/${scanId}`, base).toString();
+            const r = await fetchFn(statusUrl, { headers: { 'Authorization': `Bearer ${cfg.apiKey}`, 'Accept': 'application/json' } });
+
+            if (r.status === 429) {
+              let retrySeconds = null;
+              try { const j = await r.json(); if (j && j.retry_after) retrySeconds = j.retry_after; } catch (e) {}
+              try { const ra = r.headers.get && r.headers.get('retry-after'); if (!retrySeconds && ra) retrySeconds = parseInt(ra, 10); } catch (e) {}
+              if (retrySeconds) console.error(chalk.yellow(`Rate limit reached. Try again in ${retrySeconds} seconds.`)); else console.error(chalk.yellow('Rate limit reached. Try again later.'));
+              process.exit(1);
+            }
+
+            let data = null;
+            try { data = await r.json(); } catch (e) { data = null; }
+
+            if (data) {
+              if (data.queuePosition !== undefined) console.log(chalk.cyan('Queue position:'), data.queuePosition);
+              if (data.progress !== undefined) console.log(chalk.cyan('Progress:'), String(data.progress) + '%');
+              if (data.status) console.log(chalk.cyan('Status:'), data.status);
+              if (data.stage) console.log(chalk.dim('Stage:'), data.stage);
+            } else {
+              console.log(chalk.dim('Waiting for server response...'));
+            }
+
+            const done = data && (data.status === 'finished' || data.status === 'completed' || data.status === 'done');
+            if (done) {
+              console.log(chalk.green('Scan finished. Full results:'));
+              console.log(JSON.stringify(data, null, 2));
+              return;
+            }
+
+            try { const ra = r.headers.get && r.headers.get('retry-after'); if (ra) { const secs = parseInt(ra, 10); if (!Number.isNaN(secs)) interval = Math.max(interval, secs * 1000); } } catch (e) {}
+
+            await sleep(interval);
+          }
+        }
+
+        // Default (no wait): pretty summary
+        printScanSummary(resp.body);
+      } catch (err) { const msg = err && err.message ? err.message : String(err); console.error(chalk.red('Network error:'), msg); process.exit(1); }
+    });
+
+  if (!argv || argv.length === 0) { program.help(); return; }
+  await program.parseAsync(argv, { from: 'user' });
+}
+
+module.exports = { run };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "subto",
+  "version": "0.1.0",
+  "description": "Subto CLI — thin wrapper around the Subto.One API",
+  "bin": {
+    "subto": "bin/subto.js"
+  },
+  "preferGlobal": true,
+  "main": "bin/subto.js",
+  "license": "MIT",
+  "files": [
+    "bin/",
+    "index.js",
+    "README.md",
+    "docs/",
+    "scripts/",
+    "dist/"
+  ],
+  "homepage": "https://subto.one",
+  "repository": {
+    "type": "git",
+    "url": "https://subto.one"
+  },
+  "bugs": {
+    "url": "https://subto.one"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prepublishOnly": "node ./scripts/prepublish-check.js"
+  },
+  "dependencies": {
+    "commander": "^11.0.0",
+    "chalk": "^5.3.0"
+  }
+}

package/scripts/prepublish-check.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+function fail(msg) { console.error('prepublish-check:', msg); process.exit(1); }
+const root = path.resolve(__dirname, '..');
+const pkgPath = path.join(root, 'package.json');
+if (!fs.existsSync(pkgPath)) fail('package.json not found');
+let pkg;
+try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch (e) { fail('Failed to parse package.json: ' + e.message); }
+if (!pkg.bin || !pkg.bin.subto) fail('package.json `bin` must contain a `subto` mapping');
+if (pkg.bin.subto !== './bin/subto.js' && pkg.bin.subto !== 'bin/subto.js') fail('package.json `bin.subto` must be "./bin/subto.js"');
+const entry = path.join(root, 'bin', 'subto.js');
+if (!fs.existsSync(entry)) fail('CLI entry file bin/subto.js not found');
+try { const st = fs.statSync(entry); const mode = st.mode | 0o100; fs.chmodSync(entry, mode); } catch (e) { console.warn('prepublish-check: warning: could not set executable bit:', e.message); }
+console.log('prepublish-check: ok');
+process.exit(0);