The chell vocabulary: build with the shell’s metaphors

# Exemplar 10 — filesystem round-trip, chell style.
#
# Create → write → read → remove, entirely inside the CUBE filesystem.
# Run with -e (stop on error): the script aborts on the first failed
# command and exits non-zero, so a clean exit IS the assertion. The CUBE
# ends the run exactly as it began.
#
# Connect once first (see README "known quirks"), then:
#   chell -e -f exemplars/chell/10_fs_roundtrip.chell

# Start from the home directory (cd with no argument goes home).
cd

# Self-heal: a previous failed run may have left the scratch directory
# behind, and recreating over its remains upsets the CUBE. POSIX rm -f
# semantics make this a no-op on a clean start.
rm -rf e2e-chell-scratch

# Make a scratch directory and enter it.
mkdir e2e-chell-scratch
cd e2e-chell-scratch

# Write a file with known content; `cat` echoes it straight back from
# CUBE storage — the round-trip proof.
touch --withContents "hello from the chell exemplar" hello.txt
ls -l
cat hello.txt

# Remove the file, then the directory, and show the home listing again —
# eyeball that e2e-chell-scratch is gone.
rm hello.txt
cd ..
rm -r e2e-chell-scratch
ls

/**
 * @file Standalone example — the typed chell API.
 *
 * The complete program: connect with cumin, then drive the shell's
 * vocabulary as function calls. No command line is assembled and no parser
 * runs; each method enters the same implementation the shell's parsed
 * command enters, and returns the command's envelope with its model slot
 * typed, so results are read as data without a cast.
 *
 * Run with the CUBE settings in the environment:
 *
 *   CUBE_URL=https://cube.chrisproject.org/api/v1/ \
 *   CUBE_USER=alice CUBE_PASSWORD=secret \
 *   node exemplars/ts/dist/standalone/chell_typed.js
 *
 * @module
 */
import { chrisConnection_init, NodeStorageProvider, type ChRISConnection } from '@fnndsc/cumin';
import { chellApi_create, type ChellApi, type TypedEnvelope } from '@fnndsc/brasa';

/**
 * Round-trips a file through the CUBE filesystem in typed calls.
 */
async function main(): Promise<void> {
  const url: string | undefined = process.env.CUBE_URL;
  const user: string | undefined = process.env.CUBE_USER;
  const password: string | undefined = process.env.CUBE_PASSWORD;
  if (!url || !user || !password) {
    console.error('Set CUBE_URL, CUBE_USER and CUBE_PASSWORD.');
    process.exit(2);
  }

  const connection: ChRISConnection = await chrisConnection_init(new NodeStorageProvider());
  if (!(await connection.connection_connect({ url, user, password, debug: false }))) {
    console.error('Authentication failed.');
    process.exit(1);
  }

  const sh: ChellApi = await chellApi_create();
  const scratch: string = `typed-${Date.now().toString(36)}`;

  await sh.cd(`/home/${user}`);
  const where: TypedEnvelope<'fs.cwd'> = await sh.pwd();
  if (where.status !== 'ok' || !where.model) {
    console.error('pwd failed');
    process.exit(1);
  }
  console.log(`working in ${where.model.data.path}`);

  const made: TypedEnvelope<'fs.mkdir'> = await sh.mkdir(scratch);
  if (made.status !== 'ok') {
    console.error(made.renderedErr ?? 'mkdir failed');
    process.exit(1);
  }

  const wrote: TypedEnvelope<'fs.touch'> = await sh.touch(`${scratch}/hello.txt`, {
    contents: 'hello from the typed API',
  });
  // The model is data, not text: outcomes are read field by field.
  const created: boolean = wrote.status === 'ok'
    && (wrote.model?.data ?? []).every((outcome) => outcome.created);
  if (!created) {
    console.error(wrote.renderedErr ?? 'touch failed');
    process.exit(1);
  }
  console.log(`created ${wrote.model?.data[0]?.path}`);

  // Listings and content are data, not scraped text.
  const listing: TypedEnvelope<'fs.listing'> = await sh.ls(scratch, { long: true });
  const names: string[] = (listing.model?.data[0]?.items ?? []).map((item) => item.name);
  console.log(`listed: ${names.join(', ')}`);

  const content: TypedEnvelope<'fs.cat'> = await sh.cat(`${scratch}/hello.txt`);
  if (!content.rendered.includes('hello from the typed API')) {
    console.error('cat content mismatch');
    process.exit(1);
  }
  console.log('content verified');

  // Copy and rename, still as data.
  await sh.mkdir(`${scratch}/sub`);
  const copied: TypedEnvelope<'fs.cp'> = await sh.cp(`${scratch}/hello.txt`, `${scratch}/sub`);
  if (copied.status !== 'ok' || copied.model?.data.copied !== 1) {
    console.error('cp failed');
    process.exit(1);
  }
  const renamed: TypedEnvelope<'fs.mv'> = await sh.mv(`${scratch}/sub/hello.txt`, `${scratch}/sub/renamed.txt`);
  if (renamed.status !== 'ok') {
    console.error(renamed.renderedErr ?? 'mv failed');
    process.exit(1);
  }
  console.log('copied and renamed');

  const gone: TypedEnvelope<'fs.rm'> = await sh.rm(scratch, { recursive: true });
  if (gone.status !== 'ok') {
    console.error(gone.renderedErr ?? 'rm failed');
    process.exit(1);
  }
  console.log(`removed ${scratch}`);
}

main().catch((error: unknown) => {
  console.error(error instanceof Error ? error.message : String(error));
  process.exit(1);
});

/**
 * @file Standalone example — program with the shell's vocabulary.
 *
 * The complete program: connect with cumin, create the real chell engine,
 * and then work entirely in shell metaphors. No salsa calls appear here;
 * the API is `ls`, `mkdir`, `touch`, `cat`, `rm`, exactly the lines a chell
 * user would type, each returning typed envelopes instead of printing to a
 * terminal.
 *
 * Run with the CUBE settings in the environment:
 *
 *   CUBE_URL=https://cube.chrisproject.org/api/v1/ \
 *   CUBE_USER=alice CUBE_PASSWORD=secret \
 *   node exemplars/ts/dist/standalone/chell_vocabulary.js
 *
 * @module
 */
import { chrisConnection_init, NodeStorageProvider, type ChRISConnection, type CommandEnvelope } from '@fnndsc/cumin';
import { engine_create, type BrasaEngine } from '@fnndsc/brasa';

/**
 * Executes one shell line and returns its first envelope, exiting on error.
 *
 * @param engine - The chell engine.
 * @param line - The shell line to run, exactly as a user would type it.
 * @returns The command's envelope.
 */
async function line_run(engine: BrasaEngine, line: string): Promise<CommandEnvelope> {
  const envelopes: CommandEnvelope[] = await engine.line_execute(line);
  const first: CommandEnvelope | undefined = envelopes[0];
  if (!first || first.status !== 'ok') {
    console.error(`failed: ${line}\n${first?.renderedErr ?? ''}`);
    process.exit(1);
  }
  return first;
}

/**
 * Round-trips a file through the CUBE filesystem in shell vocabulary.
 */
async function main(): Promise<void> {
  const url: string | undefined = process.env.CUBE_URL;
  const user: string | undefined = process.env.CUBE_USER;
  const password: string | undefined = process.env.CUBE_PASSWORD;
  if (!url || !user || !password) {
    console.error('Set CUBE_URL, CUBE_USER and CUBE_PASSWORD.');
    process.exit(2);
  }

  const connection: ChRISConnection = await chrisConnection_init(new NodeStorageProvider());
  if (!(await connection.connection_connect({ url, user, password, debug: false }))) {
    console.error('Authentication failed.');
    process.exit(1);
  }

  // The same engine chell's REPL drives; here your program is the surface.
  const engine: BrasaEngine = await engine_create();

  const scratch: string = `vocab-${Date.now().toString(36)}`;
  const content: string = 'hello from the shell vocabulary';

  // Work exactly as a shell user would: navigate, then use relative paths.
  await line_run(engine, `cd /home/${user}`);
  await line_run(engine, `mkdir ${scratch}`);
  await line_run(engine, `cd ${scratch}`);
  await line_run(engine, `touch --withContents "${content}" hello.txt`);

  // `cat` returns the file's bytes in the envelope's rendered channel.
  const catted: CommandEnvelope = await line_run(engine, 'cat hello.txt');
  if (!(catted.rendered ?? '').includes(content)) {
    console.error('cat did not return the written content');
    process.exit(1);
  }
  console.log('round trip verified, in shell vocabulary');

  await line_run(engine, 'cd ..');
  await line_run(engine, `rm -r ${scratch}`);
  console.log(`removed ${scratch}`);
}

main().catch((error: unknown) => {
  console.error(error instanceof Error ? error.message : String(error));
  process.exit(1);
});

      # The operator mints a token for the identity by hand; the plaintext is shown once and carried on stdin.
      "$PORTER_BIN" --mint "$E2E_USER" --name "nightly@$(hostname -s)" | sed -n 2p \
        | node packages/chell/dist/index.js auth login --door "http://127.0.0.1:${PORTER_PORT:-4180}" --with-token
      # From here no flags are needed: this door is the default for this config.
      node packages/chell/dist/index.js auth status
      node packages/chell/dist/index.js -c pwd
      node packages/chell/dist/index.js -e -c "cd /nowhere; pwd" || true   # -e stops at the first error
      node packages/chell/dist/index.js auth logout