tshex-cli 1.0.28 → 1.0.30

package/build/main.js

@@ -1,159 +1,2 @@
 #!/usr/bin/env node
-import { program } from 'commander';
-import fs from 'node:fs';
-import path from 'node:path';
-import readline from 'node:readline/promises';
-import { stdin as input, stdout as output } from 'node:process';
-function readPackageJson() {
-    const filePath = path.join(import.meta.dirname, '..', 'package.json');
-    const fileContents = fs.readFileSync(filePath, 'utf-8');
-    return JSON.parse(fileContents);
-}
-function executeCreateProject(templatesDir, projectDir) {
-    try {
-        fs.cpSync(path.join(templatesDir, 'lib'), projectDir, {
-            recursive: true,
-            filter: (src) => src.endsWith('.gitkeep') === false
-        });
-        console.log('Project created successfully');
-    }
-    catch (err) {
-        console.error(err);
-    }
-}
-function executeCreateContext(templatesDir, contextDir) {
-    try {
-        fs.cpSync(path.join(templatesDir, 'ctx'), contextDir, {
-            recursive: true,
-            filter: (src) => src.endsWith('.gitkeep') === false
-        });
-        console.log('Context created successfully');
-    }
-    catch (err) {
-        console.error(err);
-    }
-}
-function executeCreateReactContext(templatesDir, contextDir) {
-    try {
-        fs.cpSync(path.join(templatesDir, 'ctx-react'), contextDir, {
-            recursive: true,
-            filter: (src) => src.endsWith('.gitkeep') === false
-        });
-        console.log('React context created successfully');
-    }
-    catch (err) {
-        console.error(err);
-    }
-}
-function executeCreateTests(sourceDir, destinationDir, fileContents, ignoredSourceDir, rootSourceDir = sourceDir) {
-    const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
-    if (fs.existsSync(destinationDir) === false) {
-        fs.mkdirSync(destinationDir, { recursive: true });
-    }
-    for (const entry of entries) {
-        const sourcePath = path.join(sourceDir, entry.name);
-        const destinationPath = path.join(destinationDir, entry.name);
-        if (entry.isDirectory()) {
-            if (entry.name === 'shared' && sourceDir === rootSourceDir) {
-                continue;
-            }
-            if (ignoredSourceDir !== undefined && sourcePath.startsWith(ignoredSourceDir)) {
-                continue;
-            }
-            if (fs.existsSync(destinationPath) && fs.statSync(destinationPath).isDirectory() === false) {
-                continue;
-            }
-            executeCreateTests(sourcePath, destinationPath, fileContents, ignoredSourceDir, rootSourceDir);
-            continue;
-        }
-        if (entry.isFile() && entry.name.endsWith('.ts') && fs.existsSync(destinationPath) === false) {
-            fs.writeFileSync(destinationPath, fileContents);
-        }
-    }
-}
-async function ensureTestsDirectory(testsRootDir) {
-    if (fs.existsSync(testsRootDir)) {
-        if (fs.statSync(testsRootDir).isDirectory() === false) {
-            throw new Error(`Tests path exists but is not a directory: ${testsRootDir}`);
-        }
-        return;
-    }
-    const rl = readline.createInterface({ input, output });
-    try {
-        const answer = await rl.question(`Tests directory does not exist at ${testsRootDir}. Create it? (y/N) `);
-        if (answer.trim().toLowerCase() !== 'y') {
-            return false;
-        }
-    }
-    finally {
-        rl.close();
-    }
-    fs.mkdirSync(testsRootDir, { recursive: true });
-    return true;
-}
-async function main(program) {
-    const templatesDir = path.join(import.meta.dirname, '..', 'templates');
-    const options = program.opts();
-    let targetDir = path.resolve(options.dir ?? process.cwd());
-    if (Object.keys(options).length === 0) {
-        program.help();
-    }
-    if (fs.existsSync(targetDir) === false) {
-        fs.mkdirSync(targetDir, { recursive: true });
-    }
-    if (options.project !== undefined) {
-        targetDir = path.join(targetDir, options.project);
-        executeCreateProject(templatesDir, targetDir);
-    }
-    if (options.react === true && options.context === undefined) {
-        program.error('Option --react requires --context <name>');
-    }
-    if (options.context !== undefined) {
-        targetDir = path.join(targetDir, options.context);
-        if (options.react === true) {
-            executeCreateReactContext(templatesDir, targetDir);
-        }
-        else {
-            executeCreateContext(templatesDir, targetDir);
-        }
-    }
-    if (options.tests !== undefined) {
-        const sourceDir = path.resolve(options.tests);
-        const testsTemplateFile = path.join(templatesDir, 'tests', 'content.ts');
-        if (fs.existsSync(sourceDir) === false) {
-            program.error(`Tests source directory does not exist: ${sourceDir}`);
-        }
-        if (fs.statSync(sourceDir).isDirectory() === false) {
-            program.error(`Tests source path is not a directory: ${sourceDir}`);
-        }
-        if (fs.existsSync(testsTemplateFile) === false) {
-            program.error(`Tests template file does not exist: ${testsTemplateFile}`);
-        }
-        const testsTemplateContents = fs.readFileSync(testsTemplateFile, 'utf-8');
-        const testsRootDir = path.join(targetDir, 'tests');
-        const testsDirectoryCreated = await ensureTestsDirectory(testsRootDir);
-        if (testsDirectoryCreated === false) {
-            program.error('Tests directory creation cancelled');
-        }
-        const testsDir = path.join(testsRootDir, path.basename(sourceDir));
-        if (testsDir === sourceDir) {
-            program.error('Tests destination directory cannot be the same as the source directory');
-        }
-        executeCreateTests(sourceDir, testsDir, testsTemplateContents, testsRootDir);
-        console.log('Tests structure created successfully');
-    }
-}
-const packageJson = readPackageJson();
-program
-    .name('tshex')
-    .version(packageJson.version)
-    .option('-P, --project <name>', "creates a new project with it's shared directory")
-    .option('-C, --context <name>', 'creates a new context')
-    .option('-R, --react', 'creates a React context with --context')
-    .option('-T, --tests <path>', 'creates a .ts tests structure from an existing directory')
-    .option('--dir <path>', 'sets the directory to create the new item')
-    .parse(process.argv);
-void main(program).catch((err) => {
-    const message = err instanceof Error ? err.message : String(err);
-    program.error(message);
-});
+import{program as l}from"commander";import r from"node:fs";import n from"node:path";import p from"node:readline/promises";import{stdin as m,stdout as x}from"node:process";function h(){let e=n.join(import.meta.dirname,"..","package.json"),s=r.readFileSync(e,"utf-8");return JSON.parse(s)}function g(e,s){try{r.cpSync(n.join(e,"lib"),s,{recursive:!0,filter:t=>t.endsWith(".gitkeep")===!1}),console.log("Project created successfully")}catch(t){console.error(t)}}function j(e,s){try{r.cpSync(n.join(e,"ctx"),s,{recursive:!0,filter:t=>t.endsWith(".gitkeep")===!1}),console.log("Context created successfully")}catch(t){console.error(t)}}function S(e,s){try{r.cpSync(n.join(e,"ctx-react"),s,{recursive:!0,filter:t=>t.endsWith(".gitkeep")===!1}),console.log("React context created successfully")}catch(t){console.error(t)}}function d(e,s,t,i,c=e){let u=r.readdirSync(e,{withFileTypes:!0});r.existsSync(s)===!1&&r.mkdirSync(s,{recursive:!0});for(let o of u){let a=n.join(e,o.name),f=n.join(s,o.name);if(o.isDirectory()){if(o.name==="shared"&&e===c||i!==void 0&&a.startsWith(i)||r.existsSync(f)&&r.statSync(f).isDirectory()===!1)continue;d(a,f,t,i,c);continue}o.isFile()&&o.name.endsWith(".ts")&&r.existsSync(f)===!1&&r.writeFileSync(f,t)}}async function w(e){if(r.existsSync(e)){if(r.statSync(e).isDirectory()===!1)throw new Error(`Tests path exists but is not a directory: ${e}`);return}let s=p.createInterface({input:m,output:x});try{if((await s.question(`Tests directory does not exist at ${e}. Create it? (y/N) `)).trim().toLowerCase()!=="y")return!1}finally{s.close()}return r.mkdirSync(e,{recursive:!0}),!0}async function T(e){let s=n.join(import.meta.dirname,"..","templates"),t=e.opts(),i=n.resolve(t.dir??process.cwd());if(Object.keys(t).length===0&&e.help(),r.existsSync(i)===!1&&r.mkdirSync(i,{recursive:!0}),t.project!==void 0&&(i=n.join(i,t.project),g(s,i)),t.react===!0&&t.context===void 0&&e.error("Option --react requires --context <name>"),t.context!==void 0&&(i=n.join(i,t.context),t.react===!0?S(s,i):j(s,i)),t.tests!==void 0){let c=n.resolve(t.tests),u=n.join(s,"tests","content.ts");r.existsSync(c)===!1&&e.error(`Tests source directory does not exist: ${c}`),r.statSync(c).isDirectory()===!1&&e.error(`Tests source path is not a directory: ${c}`),r.existsSync(u)===!1&&e.error(`Tests template file does not exist: ${u}`);let o=r.readFileSync(u,"utf-8"),a=n.join(i,"tests");await w(a)===!1&&e.error("Tests directory creation cancelled");let y=n.join(a,n.basename(c));y===c&&e.error("Tests destination directory cannot be the same as the source directory"),d(c,y,o,a),console.log("Tests structure created successfully")}}var v=h();l.name("tshex").version(v.version).option("-P, --project <name>","creates a new project with it's shared directory").option("-C, --context <name>","creates a new context").option("-R, --react","creates a React context with --context").option("-T, --tests <path>","creates a .ts tests structure from an existing directory").option("--dir <path>","sets the directory to create the new item").parse(process.argv);T(l).catch(e=>{let s=e instanceof Error?e.message:String(e);l.error(s)});

package/docs/context-ports.md

@@ -21,7 +21,7 @@ surface that another actor can call or observe.
 
 The generated context starts with a single root file for ports.
 
-```ts title="users/example-ports.ts"
+```ts title="enrollment/example-ports.ts"
 export class ExamplePort {
     public doSomething(): void {
         // ...
@@ -39,32 +39,56 @@ expected to be a module that defines one or more context ports.
 #### First Port
 
 In the following example we replace the placeholder with a concrete port for
-creating a user.
+managing course enrollments.
 
-```ts title="users/example-ports.ts"
-export interface User {
-    id: string
-    email: string
-    active: boolean | null
-}
+```ts title="enrollment/example-ports.ts"
+import { InMemoryDatabaseDriver } from './application/database.ts'
+import { Course } from './domain/courses.ts'
+import { Student } from './domain/students.ts'
+import { InscriptionAggregate } from './domain/inscriptions.ts'
 
-export class UsersRegistry {
-    public async createUser(user: User): Promise<User> {
-        // ...
+const database: Record<string, Record<string, unknown>[]> = {}
+
+export class Example {
+    [property: string]: unknown
+
+    private readonly driver: InMemoryDatabaseDriver
+
+    constructor() {
+        this.driver = new InMemoryDatabaseDriver(database)
+    }
+
+    public createStudent(student: Student) {
+        const result = this.driver.connect('students').create(student.toJSON())
+        this.driver.disconnect()
+        return result
+    }
+
+    public createCourse(course: Course) {
+        const result = this.driver.connect('courses').create(course.toJSON())
+        this.driver.disconnect()
+        return result
     }
-}
-```
 
-`User` expresses the user data that crosses the boundary. `UsersRegistry` is a
-boundary object of the context and `createUser()` is one concrete capability
-that it exposes.
+    public listInscriptions() {
+        const result = this.driver.connect('inscriptions').all()
+        this.driver.disconnect()
+        return result
+    }
 
-This definition focuses on the interaction the context makes available. The
-port keeps its identity as one boundary capability while making its data and
-action explicit.
+    public createInscription(student: Student, course: Course) {
+        const inscription = InscriptionAggregate.enroll(student, course)
+        const result = this.driver.connect('inscriptions').create(inscription.toJSON())
+        this.driver.disconnect()
+        return result
+    }
+}
+```
 
-The port is the executable object that this context exposes. Types help
-describe it and make its boundary explicit.
+`Example` is a boundary object of the context. Each static method is one
+concrete capability it exposes. The port connects the boundary to a driver,
+uses domain concepts internally, and keeps infrastructure details out of the
+caller.
 
 This is the normal flow inside the context boundary:
 
@@ -83,10 +107,23 @@ capability and uses domain capabilities.
 
 As the context grows, you can keep several port modules at the context root.
 
-```ts title="users/registry.ts"
-export class UsersRegistry {
-    public async listUsers(): Promise<User[]> {
-        // ...
+```ts title="enrollment/courses.ts"
+import { CoursesService } from './application/services.ts'
+import { Course } from './domain/courses.ts'
+
+export class CoursesPort {
+    constructor(private readonly service: CoursesService) {}
+
+    public all(): Record<string, unknown>[] {
+        return this.service.all()
+    }
+
+    public create(name: string, description: string, hours: number): boolean {
+        return this.service.create(new Course(name, description, hours))
+    }
+
+    public delete(course: Course): boolean {
+        return this.service.delete(course)
     }
 }
 ```
@@ -110,9 +147,10 @@ in the generated folders.
 
 ```mermaid
 flowchart TD
-    users["users/"] --> registry["registry.ts"]
-    users --> application["application/"]
-    users --> domain["domain/"]
+    enrollment["enrollment/"] --> examplePort["example-ports.ts"]
+    enrollment --> courses["courses.ts"]
+    enrollment --> application["application/"]
+    enrollment --> domain["domain/"]
 ```
 
 This layout keeps the context boundary visible from the top level. It also

package/docs/generated-file-reference.md

@@ -85,8 +85,9 @@ The generated template also includes a small set of data-access abstractions.
 
 | File | Responsibility |
 | --- | --- |
+| `shared/application/data/capabilities.ts` | Declares the operation capability interfaces: `Listable`, `Filterable`, `Sortable`, `Creatable`, `Updatable`, `Deletable`, `Aggregatable`, and `Relatable`. |
 | `shared/application/data/drivers.ts` | Declares `DriverAdapter`, the connection contract with a data source. |
-| `shared/application/data/managers.ts` | Declares `DataManager`, `DatasetManager`, and plain-record operations. |
+| `shared/application/data/managers.ts` | Declares `DataManager` and `DatasetManager`. |
 | `shared/application/data/repositories.ts` | Declares `Repository`, which transforms raw records into domain representations. |
 
 These contracts belong to the application layer because they define how the

package/docs/library-structure.md

@@ -18,7 +18,7 @@ flowchart TD
     root["Library root"] --> types["types/"]
     root --> main["main.ts"]
     root --> shared["shared/"]
-    root --> users["users/"]
+    root --> enrollment["enrollment/"]
 ```
 
 `types/` groups the root-level type declarations. `main.ts` starts as a
@@ -69,7 +69,7 @@ capability.
 
 ```mermaid
 flowchart TD
-    contexts["Contexts"] --> users["users/"]
+    contexts["Contexts"] --> enrollment["enrollment/"]
     contexts --> billing["billing/"]
     contexts --> inventory["inventory/"]
     contexts --> sales["sales/"]
@@ -85,10 +85,10 @@ Every generated context starts with the same internal structure.
 
 ```mermaid
 flowchart TD
-    users["users/"] --> ports["example-ports.ts"]
-    users --> adapters["adapters/"]
-    users --> application["application/"]
-    users --> domain["domain/"]
+    enrollment["enrollment/"] --> ports["example-ports.ts"]
+    enrollment --> adapters["adapters/"]
+    enrollment --> application["application/"]
+    enrollment --> domain["domain/"]
 ```
 
 `example-ports.ts` is an example module in the root communication surface of
@@ -189,6 +189,22 @@ application services use domain capabilities, while adapters can depend on
 ports and third-party libraries. The port branch stops at the boundary because
 what exists beyond that port depends on the system that implements it.
 
+```ts title="main.ts"
+import { Example } from './enrollment/example-ports.ts'
+import { Student } from './enrollment/domain/students.ts'
+import { Course } from './enrollment/domain/courses.ts'
+
+const example = new Example()
+const student = new Student('Ada Lovelace', 'ada@example.com')
+const course = new Course('Mathematics', 'Fundamentals of algebra and calculus', 40)
+
+example.createStudent(student)
+example.createCourse(course)
+example.createInscription(student, course)
+
+console.log(example.listInscriptions())
+```
+
 #### Next Step
 
 Use this structure as the default layout for new code. When you need to inspect