feat: SORT ON <field>[/D] TO <newtable> (#8) (#14)

* docs: SORT TO design spec (thin alias) (#8)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat: SORT ON <field>[/D] TO <newtable> (#8)

Writes a sorted copy of the active table to a new table. /D sorts
descending; the active SET FILTER is honoured. Errors when no table is
in use, the field is unknown, or the target already exists.

Thin alias over SQLite's CREATE TABLE AS SELECT ... ORDER BY — the new
table is a plain snapshot (inferred affinities, no source PK/constraints).
SORT is largely redundant given live indexes + ORDER BY; it exists for
dBASE III dialect fidelity.

Bumps version to 0.6.3; adds parser + integration tests, HELP text, and
README/CLAUDE command-table rows.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: mark SORT TO spec as implemented (#8)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: DDecoene

CHANGELOG.md

@@ -7,6 +7,16 @@ Versions follow [Semantic Versioning](https://semver.org/) — minor bump per su
 
 ---
 
+## [0.6.3] — 2026-06-24 — `SORT TO`
+
+### Added
+- **`SORT ON <field>[/D] TO <newtable>`** (#8) — writes a sorted copy of the active table to a new table. `/D` sorts descending (default ascending), and the active `SET FILTER` is honoured. Errors if no table is in use, the field doesn't exist, or the target table already exists.
+
+### Notes
+- Implemented as a thin alias over SQLite's `CREATE TABLE … AS SELECT … ORDER BY`. The new table is therefore a plain snapshot — column affinities are inferred and the source PK/constraints are **not** carried over. `SORT` is largely redundant given live indexes + `ORDER BY`; it exists for dBASE III dialect fidelity.
+
+---
+
 ## [0.6.2] — 2026-06-24 — Suspended-program fix
 
 ### Fixed

CLAUDE.md

@@ -137,6 +137,7 @@ WebBase-III supports **unlimited work areas** (no DOS 10-area limit). Cross-area
 | `LIST INDEXES` | Print all indexes for current table with active marker |
 | `SEEK <expr>` | Position record pointer at first index match |
 | `FIND <string>` | Alias for SEEK (unquoted string — dBASE III legacy) |
+| `SORT ON <field>[/D] TO <newtable>` | Sorted copy of the table into a new table (`/D` descending); honours active filter. Thin alias over `CREATE TABLE AS SELECT … ORDER BY` |
 
 > Index expressions support built-in functions: `INDEX ON UPPER(lastname) TO BYUPPER`
 

README.md

@@ -203,6 +203,7 @@ WebBase-III supports **unlimited work areas** — each independently holding a t
 | `LIST INDEXES` | Print all indexes for current table with `*` active marker |
 | `SEEK <expr>` | Position record pointer at first index match |
 | `FIND <string>` | Alias for SEEK (unquoted string — dBASE III legacy form) |
+| `SORT ON <field>[/D] TO <newtable>` | Write a sorted copy of the table to a new table; `/D` = descending; honours the active filter |
 
 ### Reports
 

docs/superpowers/specs/2026-06-24-sort-to-design.md

@@ -0,0 +1,62 @@
+# SORT TO — design (thin alias)
+
+Issue: #8 — `SORT TO` — physically sorted copy of a table.
+
+**Status:** Implemented in v0.6.3 (PR #14). Built as designed; the thin-alias
+trade-off below is the one accepted deviation from faithful dBASE behaviour.
+
+## Decision
+
+`SORT` is authentic dBASE III but largely redundant in WebBase-III's SQLite model
+(live indexes + `ORDER BY` already cover ordering). We implement it for dialect
+fidelity / nostalgia, but **thinly** — leaning on SQLite's `CREATE TABLE … AS
+SELECT … ORDER BY` rather than a faithful schema clone.
+
+## Syntax
+
+```
+SORT ON <field>[/D] TO <newtable>
+```
+
+- Single sort key (matches the issue spec; multi-key left for later if anyone asks).
+- `/D` → descending. Default ascending.
+
+## Parser
+
+- New `parseSort()`.
+- AST node: `{ type: 'SORT'; field: string; descending: boolean; target: string }`.
+
+## Executor — `doSort()`
+
+1. No active table → error.
+2. `<field>` not in the table's structure (`getStructure`) → error.
+   (Also guards the column name against injection.)
+3. `<newtable>` already exists → error (refuse to clobber; safer than dBASE's
+   silent overwrite and consistent with our other commands).
+4. Execute:
+   `CREATE TABLE <target> AS SELECT * FROM <source> [WHERE <area.filter>] ORDER BY <field> [DESC]`
+   - Honors the active `SET FILTER`.
+   - Ignores any active index — SORT defines its own order (matches dBASE III).
+5. Output: `Sorted N record(s) into <target>.`
+
+## Accepted trade-off
+
+`CREATE TABLE AS SELECT` produces a plain table: column affinities are inferred
+and PK/constraints are **not** carried over. Acceptable for a sorted snapshot;
+this is the explicit cost of the thin-alias approach. Noted in CHANGELOG.
+
+## Tests (`tests/Session.test.ts`)
+
+- Ascending order into new table.
+- `/D` descending.
+- Active filter honored.
+- Error on missing field.
+- Error on pre-existing target.
+
+## Definition of done
+
+- Tests pass.
+- Version `0.6.2 → 0.6.3` (patch — small command addition).
+- CHANGELOG entry.
+- README + CLAUDE.md command tables gain a `SORT ON … TO …` row.
+- Tag `v0.6.3` after the PR merges to `main`.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "webbase-iii",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "dBASE III is back. In your browser. USE customers like it's 1984.",
   "private": true,
   "type": "module",

src/interpreter/Executor.ts

@@ -178,6 +178,7 @@ export class Executor implements IndexCommandsHost {
         case 'SET_INDEX':   return this.indexCmds.doSetIndex(node.tag);
         case 'REINDEX':     return this.indexCmds.doReindex();
         case 'LIST_INDEXES':return this.indexCmds.doListIndexes();
+        case 'SORT':        return this.doSort(node.field, node.descending, node.target);
         case 'SEEK':        return this.indexCmds.doSeek(node.value);
         case 'FIND':        return this.indexCmds.doFind(node.value);
         case 'DO_CASE':       return this.doCase(node.cases, node.otherwise);
@@ -601,6 +602,33 @@ export class Executor implements IndexCommandsHost {
     return { output: [{ text: `Table created: ${name}`, cls: 'ok' }] };
   }
 
+  private async doSort(field: string, descending: boolean, target: string): Promise<ExecResult> {
+    const source = this.area.table;
+    if (!source) {
+      return { output: [{ text: 'SORT: no table in use', cls: 'error' }] };
+    }
+    // Validate the sort field against the table's columns (also guards the
+    // column name we splice into the ORDER BY clause). SQLite column matching
+    // is case-insensitive, so compare uppercased names.
+    const cols = await this.db.getStructure(source);
+    const col = cols.find(c => c.name.toUpperCase() === field.toUpperCase());
+    if (!col) {
+      return { output: [{ text: `SORT: no such field: ${field}`, cls: 'error' }] };
+    }
+    if (await this.db.tableExists(target)) {
+      return { output: [{ text: `SORT: target table already exists: ${target}`, cls: 'error' }] };
+    }
+    // Thin alias: lean on SQLite's CREATE TABLE ... AS SELECT ... ORDER BY.
+    // Honors the active filter; ignores any active index (SORT defines its own order).
+    const where = this.area.filter ? ` WHERE ${this.area.filter}` : '';
+    const dir = descending ? ' DESC' : '';
+    await this.db.exec(
+      `CREATE TABLE ${q(target)} AS SELECT * FROM ${q(source)}${where} ORDER BY ${q(col.name)}${dir}`
+    );
+    const count = await this.db.getRowCount(target);
+    return { output: [{ text: `Sorted ${count} record(s) into ${target}.`, cls: 'ok' }] };
+  }
+
   private async doDropTable(name: string): Promise<ExecResult> {
     await this.db.exec(`DROP TABLE IF EXISTS ${q(name)}`);
     this.indexStore?.dropTable(name);
@@ -645,6 +673,7 @@ export class Executor implements IndexCommandsHost {
       { text: 'REINDEX                  — rebuild SQLite indexes' },
       { text: 'SEEK <value>             — position to first match in active index' },
       { text: 'FIND <string>            — same as SEEK (legacy string form)' },
+      { text: 'SORT ON <field>[/D] TO <newtable> — sorted copy of the table' },
       { text: 'CREATE REPORT <name>    — create a new report definition (opens editor)' },
       { text: 'MODIFY REPORT <name>    — edit an existing report definition' },
       { text: 'REPORT FORM <name>      — run report: ASCII + HTML preview' },

src/interpreter/Lexer.ts

@@ -13,7 +13,7 @@ const KWS = new Set([
   'COUNT','LOCATE','CONTINUE','QUIT','FIELDS','HELP',
   'AND','OR','NOT','TRUE','FALSE','CREATE','TABLE','DROP','INDEX','ON',
   'INPUT','ACCEPT','DISPLAY','DATABASE','FOR','NEXT',
-  'SEEK','FIND','REINDEX','INDEXES',
+  'SEEK','FIND','REINDEX','INDEXES','SORT',
   // Multi-work-area
   'SELECT','RELATION','ALIAS','AREAS','INTO',
   // DO CASE control flow

src/interpreter/Parser.ts

@@ -57,6 +57,7 @@ export type ASTNode =
   | { type: 'SET_INDEX';   tag: string | null }
   | { type: 'REINDEX' }
   | { type: 'LIST_INDEXES' }
+  | { type: 'SORT'; field: string; descending: boolean; target: string }
   | { type: 'SEEK';        value: Expr }
   | { type: 'FIND';        value: string }
   | { type: 'UNKNOWN';     raw: string };
@@ -143,6 +144,7 @@ export class Parser {
         throw new Error('Expected FORM after REPORT');
       }
       case 'INDEX':    return this.parseIndexOn();
+      case 'SORT':     return this.parseSort();
       case 'REINDEX':  this.adv(); return { type: 'REINDEX' };
       case 'SEEK':     this.adv(); return { type: 'SEEK', value: this.expr() };
       case 'FIND':     { this.adv(); const val = this.peek().val; this.adv(); return { type: 'FIND', value: val }; }
@@ -242,6 +244,25 @@ export class Parser {
     return { type: 'SET_FILTER', expr: parts.length ? parts.join(' ') : null };
   }
 
+  private parseSort(): ASTNode {
+    this.adv(); // SORT
+    this.expectKw('ON');
+    const field = this.ident();
+    // Optional direction qualifier: /D (descending) or /A (ascending).
+    // The lexer splits `field/D` into ID, OP('/'), ID('D').
+    let descending = false;
+    if (this.peek().type === 'OP' && this.peek().val === '/') {
+      this.adv(); // '/'
+      const dir = this.ident().toUpperCase();
+      descending = dir === 'D';
+    }
+    if (!field) throw new Error('SORT requires a field before TO');
+    this.expectKw('TO');
+    const target = this.ident();
+    if (!target) throw new Error('SORT requires a target table after TO');
+    return { type: 'SORT', field, descending, target };
+  }
+
   private parseIndexOn(): ASTNode {
     this.adv(); // INDEX
     this.expectKw('ON');

tests/Session.test.ts

@@ -742,6 +742,89 @@ describe('Parser: multi-work-area nodes', () => {
     const nodes = parse('DELETE ALL');
     expect(nodes[0]).toEqual({ type: 'DELETE', scope: 'ALL' });
   });
+
+  it('parses SORT ON field TO target', () => {
+    const nodes = parse('SORT ON name TO sorted');
+    expect(nodes[0]).toEqual({ type: 'SORT', field: 'NAME', descending: false, target: 'SORTED' });
+  });
+
+  it('parses SORT ON field/D TO target as descending', () => {
+    const nodes = parse('SORT ON age/D TO sorted');
+    expect(nodes[0]).toEqual({ type: 'SORT', field: 'AGE', descending: true, target: 'SORTED' });
+  });
+});
+
+describe('SORT TO integration', () => {
+  async function withTable() {
+    const { session, sent } = makeSession();
+    const db = uniqueDb();
+    await session.handleMessage({ type: 'command', text: `USE DATABASE ${db}` });
+    await session.handleMessage({ type: 'command', text: 'CREATE TABLE people (name TEXT, age NUMERIC)' });
+    await session.handleMessage({ type: 'command', text: 'USE people' });
+    for (const [name, age] of [['Carol', 40], ['Alice', 30], ['Bob', 25]] as const) {
+      await session.handleMessage({ type: 'command', text: 'APPEND RECORD' });
+      await session.handleMessage({ type: 'command', text: `REPLACE name WITH "${name}", age WITH ${age}` });
+    }
+    return { session, sent };
+  }
+
+  function listText(sent: any[]) {
+    return sent.filter(m => m.type === 'output')
+      .flatMap((m: any) => m.lines.map((l: any) => l.text)).join(' | ');
+  }
+
+  it('SORT ON name TO creates a table ordered ascending', async () => {
+    const { session, sent } = await withTable();
+    await session.handleMessage({ type: 'command', text: 'SORT ON name TO people_sorted' });
+    sent.length = 0;
+    await session.handleMessage({ type: 'command', text: 'USE people_sorted' });
+    await session.handleMessage({ type: 'command', text: 'LIST' });
+    const text = listText(sent);
+    expect(text.indexOf('Alice')).toBeLessThan(text.indexOf('Bob'));
+    expect(text.indexOf('Bob')).toBeLessThan(text.indexOf('Carol'));
+  });
+
+  it('SORT ON field/D produces descending order', async () => {
+    const { session, sent } = await withTable();
+    await session.handleMessage({ type: 'command', text: 'SORT ON age/D TO people_desc' });
+    sent.length = 0;
+    await session.handleMessage({ type: 'command', text: 'USE people_desc' });
+    await session.handleMessage({ type: 'command', text: 'LIST' });
+    const text = listText(sent);
+    expect(text.indexOf('Carol')).toBeLessThan(text.indexOf('Alice'));
+    expect(text.indexOf('Alice')).toBeLessThan(text.indexOf('Bob'));
+  });
+
+  it('SORT honors the active filter', async () => {
+    const { session, sent } = await withTable();
+    await session.handleMessage({ type: 'command', text: 'SET FILTER TO age > 28' });
+    await session.handleMessage({ type: 'command', text: 'SORT ON name TO people_filtered' });
+    sent.length = 0;
+    await session.handleMessage({ type: 'command', text: 'USE people_filtered' });
+    await session.handleMessage({ type: 'command', text: 'LIST' });
+    const text = listText(sent);
+    expect(text).toContain('Alice');
+    expect(text).toContain('Carol');
+    expect(text).not.toContain('Bob');
+  });
+
+  it('SORT on a missing field reports an error', async () => {
+    const { session, sent } = await withTable();
+    sent.length = 0;
+    await session.handleMessage({ type: 'command', text: 'SORT ON nosuch TO people_bad' });
+    const err = sent.filter(m => m.type === 'output')
+      .flatMap((m: any) => m.lines).some((l: any) => l.cls === 'error');
+    expect(err).toBe(true);
+  });
+
+  it('SORT to an existing table reports an error', async () => {
+    const { session, sent } = await withTable();
+    sent.length = 0;
+    await session.handleMessage({ type: 'command', text: 'SORT ON name TO people' });
+    const err = sent.filter(m => m.type === 'output')
+      .flatMap((m: any) => m.lines).some((l: any) => l.cls === 'error');
+    expect(err).toBe(true);
+  });
 });
 
 describe('Multi-work-area integration', () => {