@grayspar/cli 0.0.1 → 0.0.3

package/README.md

@@ -32,10 +32,10 @@ A service at the root of your directory is called `app`, and one in a subfolder
 ## Share
 
 ```sh
-grayspar access add alice@company.com
+grayspar access add alice@company.example
 ```
 
-Alice gets an email with the link. Name people one by one, or a whole company at once with `@company.com`.
+Alice gets an email with the link. Name people one by one, or a whole company at once with `@company.example`.
 
 ## For scripts and agents
 
@@ -59,7 +59,7 @@ Every command answers in JSON with `--json`, and `--yes` accepts what the CLI wo
 | `unlink`    | unbind this folder from its project                                             |
 | `status`    | show what a project is doing                                                    |
 | `logs`      | show what a service printed while running, or with `--build` the last build log |
-| `restart`   | run a service again in place, keeping its volumes                               |
+| `restart`   | run a service again in place, keeping its volume                                |
 
 `grayspar <command> --help` shows each command's options.
 

package/dist/commands/access.js

@@ -25,13 +25,13 @@ function addedReceipt(added, name) {
         return receipt(`Added @${added.entry.domain} to ${name}`);
     return added.told === true
         ? receipt(`Added ${added.entry.email} to ${name} and emailed the link`)
-        : warning(`Added ${added.entry.email} to ${name}, but the email did not send.`);
+        : warning(`Added ${added.entry.email} to ${name}, but the email didn't send.`);
 }
 async function setGeneralAccess(mode, format) {
     const api = await signedInClient();
     const project = await resolveProject(api);
-    const access = await dataOrThrow(api.PUT('/api/projects/{id}/general-access', {
-        params: { path: { id: project.id } },
+    const access = await dataOrThrow(api.PUT('/api/projects/{projectId}/general-access', {
+        params: { path: { projectId: project.id } },
         body: { mode },
     }));
     printResult(format, access, () => `${receipt(`Set access of ${project.name} to ${access.mode}`)}\n${accessSentence(access.mode, project.name)}`);
@@ -41,8 +41,8 @@ async function addAccess(targets, format) {
     const project = await resolveProject(api);
     const results = [];
     for (const target of targets) {
-        results.push(await dataOrThrow(api.POST('/api/projects/{id}/access', {
-            params: { path: { id: project.id } },
+        results.push(await dataOrThrow(api.POST('/api/projects/{projectId}/access', {
+            params: { path: { projectId: project.id } },
             body: targetOf(target),
         })));
     }
@@ -51,7 +51,7 @@ async function addAccess(targets, format) {
 async function listAccess(format) {
     const api = await signedInClient();
     const project = await resolveProject(api);
-    const rows = await dataOrThrow(api.GET('/api/projects/{id}/access', { params: { path: { id: project.id } } }));
+    const rows = await dataOrThrow(api.GET('/api/projects/{projectId}/access', { params: { path: { projectId: project.id } } }));
     printResult(format, rows, () => [
         accessSentence(project.generalAccess.mode, project.name),
         '',
@@ -68,14 +68,14 @@ async function listAccess(format) {
 async function removeAccess(target, format) {
     const api = await signedInClient();
     const project = await resolveProject(api);
-    const rows = await dataOrThrow(api.GET('/api/projects/{id}/access', { params: { path: { id: project.id } } }));
+    const rows = await dataOrThrow(api.GET('/api/projects/{projectId}/access', { params: { path: { projectId: project.id } } }));
     const wanted = target.toLowerCase();
     const row = rows.find((candidate) => labelOf(candidate) === wanted);
     if (row === undefined) {
-        throw new CliError('not_shared', `${target} is not on the list for ${project.name}.`);
+        throw new CliError('not_shared', `${target} isn't on the list for ${project.name}.`);
     }
-    await dataOrThrow(api.DELETE('/api/projects/{id}/access/{accessId}', {
-        params: { path: { id: project.id, accessId: row.id } },
+    await dataOrThrow(api.DELETE('/api/projects/{projectId}/access/{accessId}', {
+        params: { path: { projectId: project.id, accessId: row.id } },
     }));
     printResult(format, { status: 'ok', removed: labelOf(row) }, () => receipt(`Removed ${labelOf(row)} from ${project.name}`));
 }
@@ -86,12 +86,12 @@ accessCommand
     .action(commandAction((format) => listAccess(format)));
 accessCommand
     .command('add')
-    .argument('<targets...>', 'email addresses, or @company.com for everyone at a company')
+    .argument('<targets...>', 'email addresses, or @company.example for everyone at a company')
     .description('let named people or a whole company open a project')
     .action(commandAction((format, _command, targets) => addAccess(targets, format)));
 accessCommand
     .command('remove')
-    .argument('<target>', 'an email address, or @company.com')
+    .argument('<target>', 'an email address, or @company.example')
     .description('take someone or a company off a project')
     .action(commandAction((format, _command, target) => removeAccess(target, format)));
 accessCommand

package/dist/commands/deploy/archive.js

@@ -1,23 +1,69 @@
-/* What git ignores stays home, matched by git's own rules in every folder's .gitignore, and a .env never goes in
-   the archive, because a value landing in an image layer would sit there for as long as the image exists. */
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+/* Git lists what to upload inside a work tree, and the .gitignore files decide elsewhere. A .env never goes in the
+   archive, because a value landing in an image layer would sit there for as long as the image exists. */
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream, createWriteStream, readFileSync } from 'node:fs';
+import { lstat, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { promisify } from 'node:util';
 import ignore, {} from 'ignore';
 import { create } from 'tar';
-const ALWAYS_SKIPPED = [
-    'node_modules',
-    '.git',
-    'dist',
-    'build',
-    'out',
-    'target',
-    'vendor',
-    '.venv',
-    '.next',
-    '.turbo',
-    'coverage',
-];
-const ENV_FILE_PATTERN = /(^|\/)\.env(\..+)?$/;
+import { CliError } from '../../lib/errors.js';
+const execFileAsync = promisify(execFile);
+const GIT_LIST_TIMEOUT_MS = 60_000;
+const GIT_LIST_MAX_BYTES = 256 * 1024 * 1024;
+const GIT_NOT_A_WORK_TREE_EXIT_CODE = 128;
+const OUTSIDE_GIT_SKIPPED = ['node_modules', '.git'];
+const LINK_FOLDER_PATTERN = /(^|\/)\.grayspar(\/|$)/;
+function isKeptOutOfUpload(path) {
+    return basename(path).startsWith('.env') || LINK_FOLDER_PATTERN.test(path);
+}
+async function listWithGit(root, ...args) {
+    const { stdout } = await execFileAsync('git', ['--literal-pathspecs', 'ls-files', '-z', ...args], { cwd: root, timeout: GIT_LIST_TIMEOUT_MS, maxBuffer: GIT_LIST_MAX_BYTES });
+    return stdout.split('\0').filter((path) => path !== '');
+}
+async function presentFiles(root, listed) {
+    const found = await Promise.all(listed.map(async (path) => ({ path, entry: await lstat(join(root, path)).catch(() => null) })));
+    const present = found.flatMap(({ path, entry }) => (entry === null ? [] : [{ path, entry }]));
+    const folder = present.find(({ entry }) => entry.isDirectory());
+    if (folder !== undefined)
+        throw new FolderListed(folder.path.replace(/\/$/, ''));
+    return present.map(({ path }) => path);
+}
+class FolderListed extends Error {
+}
+async function filesGitKeeps(root, under) {
+    let tracked;
+    let untracked;
+    try {
+        // git refuses --recurse-submodules together with --others, so the untracked files come from a second listing
+        tracked = await listWithGit(root, '--cached', '--recurse-submodules', '--', under);
+        untracked = await listWithGit(root, '--others', '--exclude-standard', '--', under);
+    }
+    catch (error) {
+        const notGit = error instanceof Error &&
+            'code' in error &&
+            (error.code === GIT_NOT_A_WORK_TREE_EXIT_CODE || error.code === 'ENOENT');
+        if (notGit)
+            return null;
+        throw error;
+    }
+    try {
+        const trackedFiles = await presentFiles(root, tracked);
+        const untrackedFiles = await presentFiles(root, untracked);
+        return [...new Set([...trackedFiles, ...untrackedFiles])];
+    }
+    catch (error) {
+        if (!(error instanceof FolderListed))
+            throw error;
+        // a folder listed as tracked is a submodule nobody checked out, and one listed as untracked holds a repository of its own
+        throw tracked.some((path) => path.replace(/\/$/, '') === error.message)
+            ? new CliError('submodule_not_checked_out', `${error.message} is a submodule that isn't checked out.\nRun git submodule update --init, then deploy again.`)
+            : new CliError('nested_repository', `${error.message} is a separate git repository, so its files can't be listed.\nAdd it to .gitignore, or make its files part of this repository.`);
+    }
+}
 function readOrEmpty(path) {
     try {
         return readFileSync(path, 'utf8');
@@ -28,9 +74,8 @@ function readOrEmpty(path) {
 }
 function ignoredBy(root) {
     const rootRules = ignore()
-        .add(ALWAYS_SKIPPED)
-        .add(readOrEmpty(join(root, '.gitignore')))
-        .add(readOrEmpty(join(root, '.dockerignore')));
+        .add(OUTSIDE_GIT_SKIPPED)
+        .add(readOrEmpty(join(root, '.gitignore')));
     const nested = new Map();
     function rulesIn(folder) {
         if (!nested.has(folder)) {
@@ -41,7 +86,7 @@ function ignoredBy(root) {
     }
     return (path, isDirectory) => {
         const asked = isDirectory ? `${path}/` : path;
-        if (ENV_FILE_PATTERN.test(path) || rootRules.ignores(asked))
+        if (rootRules.ignores(asked))
             return true;
         const folders = path.split('/').slice(0, -1);
         return folders.some((_, index) => {
@@ -50,18 +95,62 @@ function ignoredBy(root) {
         });
     };
 }
-export async function archiveOf(root) {
-    const ignored = ignoredBy(root);
-    const chunks = [];
-    const stream = create({
-        cwd: root,
-        gzip: true,
-        filter: (path, entry) => {
-            const relative = path.replace(/^\.\/?/, '');
-            return relative === '' || !ignored(relative, 'isDirectory' in entry && entry.isDirectory());
+const BYTES_PER_MEGABYTE = 1024 ** 2;
+const FIX_BY_IGNORING = "Add the files you don't need, such as build output, to .gitignore.";
+function tooManyFiles({ files }) {
+    return new CliError('too_many_files', `A deploy holds at most ${files.toLocaleString('en-US')} files, and this project has more.\n${FIX_BY_IGNORING}`);
+}
+function stopsPast({ bytes }) {
+    let written = 0;
+    return new Transform({
+        transform(chunk, _encoding, done) {
+            written += chunk.length;
+            done(written > bytes
+                ? new CliError('upload_too_large', `A deploy can be at most ${Math.floor(bytes / BYTES_PER_MEGABYTE)} MB, and this project is larger.\n${FIX_BY_IGNORING}`)
+                : null, chunk);
         },
-    }, ['.']);
-    for await (const chunk of stream)
-        chunks.push(Buffer.from(chunk));
-    return Buffer.concat(chunks);
+    });
+}
+function refuseEmptyUpload(root, under) {
+    throw new CliError('nothing_to_upload', `There are no files to deploy in ${join(root, under)}.`);
+}
+export async function archiveOf(root, under, into, limits) {
+    const path = join(into, 'archive.tgz');
+    const files = await filesGitKeeps(root, under);
+    const write = (packed) => pipeline(Readable.from(packed), stopsPast(limits), createWriteStream(path));
+    if (files === null) {
+        const ignored = ignoredBy(root);
+        let fileCount = 0;
+        await write(create({
+            cwd: root,
+            gzip: true,
+            filter: (entryPath, entry) => {
+                const relative = entryPath.replace(/^\.\/?/, '');
+                if (relative === '')
+                    return true;
+                const isDirectory = 'isDirectory' in entry && entry.isDirectory();
+                if (isKeptOutOfUpload(relative) || ignored(relative, isDirectory))
+                    return false;
+                if (!isDirectory)
+                    fileCount += 1;
+                return fileCount <= limits.files;
+            },
+        }, [under]));
+        if (fileCount === 0)
+            refuseEmptyUpload(root, under);
+        if (fileCount > limits.files)
+            throw tooManyFiles(limits);
+    }
+    else {
+        const kept = files.filter((file) => !isKeptOutOfUpload(file));
+        if (kept.length === 0)
+            refuseEmptyUpload(root, under);
+        if (kept.length > limits.files)
+            throw tooManyFiles(limits);
+        await write(create({ cwd: root, gzip: true, noDirRecurse: true }, kept));
+    }
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return { path, bytes: (await stat(path)).size, sha256: hash.digest('hex') };
 }

package/dist/commands/deploy/await-discovery.js

@@ -0,0 +1,17 @@
+import { dataOrThrow } from '../../lib/client.js';
+import { realClock, retryTransient } from '../../lib/retry-transient.js';
+export async function awaitDiscovery(api, destination, uploadId, clock = realClock) {
+    for (;;) {
+        const watched = await retryTransient((signal) => dataOrThrow(destination.kind === 'project'
+            ? api.GET('/api/projects/{projectId}/uploads/{uploadId}/discovery', {
+                params: { path: { projectId: destination.project.id, uploadId } },
+                signal,
+            })
+            : api.GET('/api/teams/{teamId}/uploads/{uploadId}/discovery', {
+                params: { path: { teamId: destination.team.id, uploadId } },
+                signal,
+            })), clock);
+        if (watched !== undefined)
+            return watched;
+    }
+}

package/dist/commands/deploy/deploy-destination.js

@@ -0,0 +1,101 @@
+import { basename } from 'node:path';
+import { dataOrThrow } from '../../lib/client.js';
+import { CliError } from '../../lib/errors.js';
+import { printNote } from '../../lib/output.js';
+import { askChoice, askText, isInteractive } from '../../lib/prompt.js';
+import { projectIsNamed, resolveProject, teamProjects } from '../../lib/resolve-project.js';
+import { resolveTeam } from '../../lib/resolve-team.js';
+import { failure } from '../../lib/ui.js';
+import { projectNameFrom } from './project-name.js';
+export function destinationOptions(projects, suggestedName) {
+    const match = projects.find((project) => project.name === suggestedName);
+    const others = projects
+        .filter((project) => project !== match)
+        .map((project) => ({ kind: 'existing', project }));
+    const create = { kind: 'create' };
+    return match === undefined
+        ? [create, ...others]
+        : [{ kind: 'existing', project: match }, create, ...others];
+}
+const NAME_RULE = 'Names use lowercase letters, numbers and single hyphens, up to 58 characters.';
+function nameProblem(name, projects) {
+    if (projectNameFrom(name) !== name)
+        return NAME_RULE;
+    return projects.some((project) => project.name === name)
+        ? `This team already has a project called ${name}.`
+        : null;
+}
+function givenName(name, projects) {
+    const problem = name === null ? NAME_RULE : nameProblem(name, projects);
+    if (name === null || problem !== null) {
+        throw new CliError('needs_a_name', `${problem ?? NAME_RULE}\nName the project with --name.`, '--name');
+    }
+    return name;
+}
+async function askProjectName(projects, suggestion) {
+    let offered = suggestion;
+    for (;;) {
+        const answer = await askText('Project name', offered, '--name');
+        const problem = nameProblem(answer, projects);
+        if (problem === null)
+            return answer;
+        process.stdout.write(`${failure(problem)}\n`);
+        offered = projectNameFrom(answer);
+    }
+}
+export async function destinationFor(api, root, link, options) {
+    if (options.name !== undefined && projectIsNamed()) {
+        throw new CliError('name_and_project', '--name creates a new project and --project names an existing one.\nGive one of them.', '--name');
+    }
+    if (projectIsNamed()) {
+        return {
+            kind: 'project',
+            project: await resolveProject(api, { followLink: false }),
+            linksFolder: false,
+        };
+    }
+    if (link !== null) {
+        const answer = await api.GET('/api/projects/{projectId}', {
+            params: { path: { projectId: link.projectId } },
+        });
+        if (answer.response.status !== 404) {
+            if (options.name !== undefined) {
+                throw new CliError('already_linked', 'This folder is already linked to a project.\nRun grayspar unlink to deploy it as a new one.', '--name');
+            }
+            return {
+                kind: 'project',
+                project: await dataOrThrow(Promise.resolve(answer)),
+                linksFolder: false,
+            };
+        }
+        printNote(options.format, 'The project this folder was linked to no longer exists.');
+    }
+    const team = await resolveTeam(api, { takeDefault: options.yes, deploying: true });
+    const projects = await teamProjects(api, team.id);
+    if (options.name !== undefined) {
+        return { kind: 'new', team, name: givenName(options.name, projects) };
+    }
+    const suggestion = projectNameFrom(basename(root));
+    const destinations = destinationOptions(projects, suggestion);
+    const [suggested] = destinations;
+    if (suggested === undefined)
+        throw new Error('no project to create');
+    if (options.yes) {
+        return suggested.kind === 'existing'
+            ? { kind: 'project', project: suggested.project, linksFolder: true }
+            : { kind: 'new', team, name: givenName(suggestion, projects) };
+    }
+    if (!isInteractive()) {
+        throw new CliError('needs_an_answer', "This folder isn't linked to a project yet, and there's no terminal to ask which.\nDeploy to a new project with --name, or to an existing one with --project.", '--name');
+    }
+    const picked = await askChoice('Select a project', 'Project', destinations.map((option, index) => ({
+        value: String(index),
+        label: option.kind === 'create' ? 'Create a new project' : option.project.name,
+    })), '--project');
+    const choice = destinations[Number(picked)] ?? suggested;
+    const destination = choice.kind === 'existing'
+        ? { kind: 'project', project: choice.project, linksFolder: true }
+        : { kind: 'new', team, name: await askProjectName(projects, suggestion) };
+    process.stdout.write('\n');
+    return destination;
+}

package/dist/commands/deploy/deploy-flags.js

@@ -4,6 +4,7 @@ const EXAMPLE_VALUE = {
     '--dockerfile': 'docker/Dockerfile',
     '--volume': '/app/data',
 };
+export const NO_PATH_VALUE = 'none';
 function servicePairs(values, flag, onlyServices) {
     return values.map((value) => {
         const separatorIndex = value.indexOf('=');
@@ -20,7 +21,10 @@ function servicePairs(values, flag, onlyServices) {
 export function parseDeployFlags(flags) {
     const volumes = new Map();
     for (const [name, path] of servicePairs(flags.volumes, '--volume', flags.services)) {
-        volumes.set(name, [...(volumes.get(name) ?? []), path]);
+        if (volumes.has(name)) {
+            throw new CliError('bad_flag', `A service keeps one volume. Give --volume once for ${name}.`, '--volume');
+        }
+        volumes.set(name, path);
     }
     return {
         onlyServices: flags.services,
@@ -43,12 +47,14 @@ export function servicesToSend(found, serviceFlags) {
     return deploying.map((name) => {
         const pathPrefix = serviceFlags.paths.get(name);
         const dockerfile = serviceFlags.dockerfiles.get(name);
-        const volumes = serviceFlags.volumes.get(name);
+        const volume = serviceFlags.volumes.get(name);
         return {
             name,
-            ...(pathPrefix === undefined ? {} : { pathPrefix }),
+            ...(pathPrefix === undefined
+                ? {}
+                : { pathPrefix: pathPrefix === NO_PATH_VALUE ? null : pathPrefix }),
             ...(dockerfile === undefined ? {} : { dockerfile }),
-            ...(volumes === undefined ? {} : { volumes }),
+            ...(volume === undefined ? {} : { volume }),
         };
     });
 }

package/dist/commands/deploy/deploy-target.js

@@ -0,0 +1,19 @@
+/* The project folder is the linked one found from where the command runs, or the current folder when nothing is
+   linked. A folder given to deploy narrows the upload to the files under it, which keep their place in that folder. */
+import { stat } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { CliError } from '../../lib/errors.js';
+import { findLink } from '../../lib/project-link.js';
+export async function deployTarget(currentFolder, folder) {
+    const link = await findLink(currentFolder);
+    const root = link?.folder ?? resolve(currentFolder);
+    const wanted = resolve(currentFolder, folder);
+    const under = relative(root, wanted) || '.';
+    if (under === '..' || under.startsWith('../') || isAbsolute(under)) {
+        throw new CliError('outside_project', `${folder} is outside the project folder ${root}.\nRun grayspar deploy from inside the project folder.`);
+    }
+    const isFolder = await stat(wanted).then((found) => found.isDirectory(), () => false);
+    if (!isFolder)
+        throw new CliError('no_such_folder', `${folder} isn't a folder.`);
+    return { link, root, under };
+}