mobilestacks 0.1.23 → 0.1.26

package/README.md

@@ -1,188 +1,192 @@
-# mobilestacks
-
-A Hardhat-style development framework for Stacks. Write, test, and deploy Clarity smart contracts with a task-based CLI, local Simnet testing, and a pluggable runtime.
-
-## Install
-
-```bash
-npm install mobilestacks
-```
-
-## Quick Start
-
-Scaffold a new project:
-
-```bash
-npx mobilestacks init
-```
-
-This generates a config file, a sample Clarity contract, and an example task.
-
-## Configuration
-
-All config lives in `mobilestacks.config.ts`:
-
-```ts
-export default {
-  networks: {
-    mainnet: { url: "https://api.mainnet.hiro.so", name: "mainnet" },
-    testnet: { url: "https://api.testnet.hiro.so", name: "testnet" },
-  },
-  defaultNetwork: "testnet",
-  wallet: {
-    privateKey: process.env.STACKS_PRIVATE_KEY,
-  },
-};
-```
-
-Secrets can live in `.env` — they override config values automatically.
-
-## CLI
-
-```bash
-npx mobilestacks                    # list all tasks
-npx mobilestacks deploy-contract    # deploy a contract
-npx mobilestacks get-balance        # check STX balance
-npx mobilestacks send-stx           # send STX
-npx mobilestacks faucet-request     # get testnet tokens
-```
-
-Missing params are prompted interactively. Run any task with `--help` for options.
-
-### Built-in Tasks
-
-| Task | What it does |
-| ---- | ------------ |
-| `deploy-contract` | Deploy a `.clar` file to mainnet/testnet |
-| `send-stx` | Transfer STX to an address |
-| `get-balance` | Check STX balance for any address |
-| `faucet-request` | Request testnet STX from the faucet |
-| `list-accounts` | List derived wallet accounts |
-| `get-tx-history` | Fetch recent transactions |
-| `call-contract-function` | Call a read-only contract function |
-| `get-contract-info` | Fetch deployed contract metadata |
-| `verify-contract` | Diff on-chain source against a local file |
-
-## Writing Tasks
-
-Drop a file in `src/tasks/` — it's auto-discovered:
-
-```ts
-import { task } from "mobilestacks";
-import { z } from "zod";
-
-task("greet", "Say hello")
-  .addParam("name", "Who to greet", { schema: z.string().min(1) })
-  .setAction(async (args, env) => {
-    return `Hello, ${args.name}! (network: ${env.config.defaultNetwork})`;
-  });
-```
-
-Subtasks and workflows are also supported:
-
-```ts
-import { subtask, runWorkflow } from "mobilestacks";
-
-// subtask tied to a parent
-subtask("deploy:validate", "Pre-deploy check", "deploy-contract")
-  .setAction(async (args, env) => { /* ... */ });
-
-// run tasks in sequence
-await runWorkflow([
-  { taskName: "deploy-contract", args: { /* ... */ } },
-  { taskName: "verify-contract", args: { /* ... */ } },
-], env);
-```
-
-## Extending the Runtime
-
-Add custom properties to the runtime environment, available in every task:
-
-```ts
-import { extendEnvironment } from "mobilestacks";
-
-extendEnvironment((env) => {
-  env.formatSTX = (micro: number) => `${(micro / 1e6).toFixed(6)} STX`;
-});
-```
-
-## Testing with Simnet
-
-Test contracts locally using the Clarinet SDK — no devnet needed:
-
-```ts
-import { describe, it, expect, beforeAll } from "vitest";
-import { Simnet } from "mobilestacks";
-import { Cl } from "@stacks/transactions";
-
-describe("My Contract", () => {
-  let simnet: Simnet;
-
-  beforeAll(async () => {
-    simnet = await Simnet.init();
-  });
-
-  it("calls hello-world", () => {
-    const deployer = simnet.getDeployer();
-    const { result } = simnet.callPublic("sample-contract", "hello-world", [], deployer);
-    expect(result).toStrictEqual(Cl.ok(Cl.stringAscii("Hello, Stacks!")));
-  });
-});
-```
-
-### Setup
-
-Contract tests need a `Clarinet.toml` and test accounts. Run the setup script once:
-
-```bash
-npm run setup:simnet
-```
-
-Then run tests:
-
-```bash
-npm test
-```
-
-## Programmatic API
-
-Use mobilestacks as a library:
-
-```ts
-import { task, subtask, extendEnvironment, Simnet, RuntimeEnvironment } from "mobilestacks";
-```
-
-## Project Structure
-
-```
-├── src/
-│   ├── cli/           # CLI entry point + init scaffolding
-│   ├── core/          # DSL, Simnet, RuntimeEnvironment, task registry
-│   ├── tasks/         # Built-in tasks (auto-loaded)
-│   ├── types/         # Zod schemas + TypeScript types
-│   └── index.ts       # Public API
-├── tests/             # Vitest test files
-├── contracts/         # Clarity contracts
-├── Clarinet.toml      # Clarinet project manifest
-└── mobilestacks.config.ts
-```
-
-## Contributing
-
-```bash
-git clone https://github.com/Wizbisy/mobilestacks.git
-cd mobilestacks
-npm install
-npm run setup:simnet   # generate test accounts
-npm test               # run all tests
-```
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
-
-## Security
-
-Private keys and seed phrases are never logged. Output is scanned for secrets and masked automatically. Keep your `.env` out of version control.
-
-## License
-
-MIT
+# mobilestacks
+
+[![npm version](https://badge.fury.io/js/mobilestacks.svg)](https://badge.fury.io/js/mobilestacks)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Hardhat-style development framework for Stacks. Write, test, and deploy Clarity smart contracts with a task-based CLI, local Simnet testing, and a pluggable runtime.
+
+## Install
+
+```bash
+npm install mobilestacks
+```
+
+## Quick Start
+
+Scaffold a new project:
+
+```bash
+npx mobilestacks init
+```
+
+This generates a config file, a sample Clarity contract, and an example task.
+
+## Configuration
+
+All config lives in `mobilestacks.config.ts`:
+
+```ts
+export default {
+  networks: {
+    mainnet: { url: 'https://api.mainnet.hiro.so', name: 'mainnet' },
+    testnet: { url: 'https://api.testnet.hiro.so', name: 'testnet' },
+  },
+  defaultNetwork: 'testnet',
+  wallet: {
+    privateKey: process.env.STACKS_PRIVATE_KEY,
+  },
+};
+```
+
+Secrets can live in `.env`; they override config values automatically.
+
+## CLI
+
+```bash
+npx mobilestacks                    # list all tasks
+npx mobilestacks deploycontract     # deploy a contract
+npx mobilestacks getbalance         # check STX balance
+npx mobilestacks sendstx            # send STX
+npx mobilestacks faucetrequest      # get testnet tokens
+```
+
+Missing required params are prompted interactively. Run any task with `--help` for options.
+
+### Built-in Tasks
+
+| Task | What it does |
+| ---- | ------------ |
+| `deploycontract` | Deploy a `.clar` file to mainnet/testnet |
+| `sendstx` | Transfer STX to an address |
+| `getbalance` | Check STX balance for any address |
+| `faucetrequest` | Request testnet STX from the faucet |
+| `listaccounts` | List derived wallet accounts |
+| `gettxhistory` | Fetch recent transactions |
+| `callcontractfunction` | Call a read-only contract function |
+| `getcontractinfo` | Fetch deployed contract metadata |
+| `verifycontract` | Diff on-chain source against a local file |
+
+## Writing Tasks
+
+Drop a file in `src/tasks/`; it is auto-discovered:
+
+```ts
+import { task } from 'mobilestacks';
+import { z } from 'zod';
+
+task('greet', 'Say hello')
+  .addParam('name', 'Who to greet', { schema: z.string().min(1) })
+  .setAction((args, env) => {
+    return `Hello, ${args.name}! (network: ${env.config.defaultNetwork})`;
+  });
+```
+
+Subtasks and workflows are also supported:
+
+```ts
+import { subtask, runWorkflow } from 'mobilestacks';
+
+subtask('deploy:validate', 'Pre-deploy check', 'deploycontract').setAction((args, env) => {
+  // validate deployment inputs
+});
+
+await runWorkflow(
+  [
+    { taskName: 'deploycontract', args: { contractName: 'sample-contract' } },
+    { taskName: 'verifycontract', args: { contractName: 'sample-contract' } },
+  ],
+  env,
+);
+```
+
+## Extending the Runtime
+
+Add custom properties to the runtime environment, available in every task:
+
+```ts
+import { extendEnvironment } from 'mobilestacks';
+
+extendEnvironment((env) => {
+  env.formatSTX = (micro: number) => `${(micro / 1e6).toFixed(6)} STX`;
+});
+```
+
+## Testing with Simnet
+
+Test contracts locally using the Clarinet SDK. No devnet is needed:
+
+```ts
+import { describe, it, expect, beforeAll } from 'vitest';
+import { Simnet } from 'mobilestacks';
+import { Cl } from '@stacks/transactions';
+
+describe('My Contract', () => {
+  let simnet: Simnet;
+
+  beforeAll(async () => {
+    simnet = await Simnet.init();
+  });
+
+  it('calls hello-world', () => {
+    const deployer = simnet.getDeployer();
+    const { result } = simnet.callPublic('sample-contract', 'hello-world', [], deployer);
+    expect(result).toStrictEqual(Cl.ok(Cl.stringAscii('Hello, Stacks!')));
+  });
+});
+```
+
+### Setup
+
+Contract tests need a `Clarinet.toml` and test accounts. Run the setup script once:
+
+```bash
+npm run setup:simnet
+```
+
+Then run tests:
+
+```bash
+npm test
+```
+
+## Programmatic API
+
+Use mobilestacks as a library:
+
+```ts
+import { task, subtask, extendEnvironment, Simnet, RuntimeEnvironment } from 'mobilestacks';
+```
+
+## Project Structure
+
+```text
+src/
+  cli/           CLI entry point and init scaffolding
+  core/          DSL, Simnet, RuntimeEnvironment, task registry
+  tasks/         Built-in tasks
+  types/         Zod schemas and TypeScript types
+  index.ts       Public API
+tests/           Vitest test files
+contracts/       Clarity contracts
+Clarinet.toml    Clarinet project manifest
+```
+
+## Contributing
+
+```bash
+git clone https://github.com/Wizbisy/mobilestacks.git
+cd mobilestacks
+npm install
+npm run setup:simnet
+npm test
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## Security
+
+Private keys and seed phrases are never logged. Output is scanned for sensitive fields and masked automatically when tasks return transaction IDs. Keep your `.env` out of version control.
+
+## License
+
+MIT

package/dist/cli/index.js

@@ -6,24 +6,66 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const chalk_1 = __importDefault(require("chalk"));
 const commander_1 = require("commander");
-const config_loading_1 = require("../config/config-loading");
-const runtime_environment_1 = require("../core/runtime-environment");
-const tasks_definitions_1 = require("../core/tasks-definitions");
-const init_1 = require("./init");
-const inquirer_1 = __importDefault(require("inquirer"));
 const fs_1 = __importDefault(require("fs"));
+const inquirer_1 = __importDefault(require("inquirer"));
 const path_1 = __importDefault(require("path"));
+const ConfigLoading_1 = require("../config/ConfigLoading");
+const RuntimeEnvironment_1 = require("../core/RuntimeEnvironment");
+const TasksDefinitions_1 = require("../core/TasksDefinitions");
+const init_1 = require("./init");
 const tasksDir = path_1.default.join(__dirname, '../tasks');
 fs_1.default.readdirSync(tasksDir)
-    .filter(f => (f.endsWith('.ts') || f.endsWith('.js')) && !f.endsWith('.d.ts') && !f.includes('.test.'))
-    .forEach(f => {
-    require(path_1.default.join(tasksDir, f));
+    .filter((fileName) => {
+    return ((fileName.endsWith('.ts') || fileName.endsWith('.js')) &&
+        !fileName.endsWith('.d.ts') &&
+        !fileName.includes('.test.'));
+})
+    .forEach((fileName) => {
+    require(path_1.default.join(tasksDir, fileName));
 });
+function getProvidedOptions(argv) {
+    return new Set(argv
+        .filter((arg) => arg.startsWith('--'))
+        .map((arg) => arg.slice(2).split('=')[0])
+        .filter(Boolean));
+}
+function parseBoolean(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        const normalized = value.toLowerCase();
+        if (['true', '1', 'yes', 'y'].includes(normalized))
+            return true;
+        if (['false', '0', 'no', 'n'].includes(normalized))
+            return false;
+    }
+    return Boolean(value);
+}
+function coerceParamValue(param, value) {
+    if (value === undefined)
+        return value;
+    if (param.type === 'number') {
+        const parsed = Number(value);
+        if (Number.isNaN(parsed)) {
+            throw new Error(`Parameter '${param.name}' must be a number.`);
+        }
+        return parsed;
+    }
+    if (param.type === 'boolean') {
+        return parseBoolean(value);
+    }
+    return value;
+}
+function getPackageVersion() {
+    const packagePath = path_1.default.resolve(__dirname, '../../package.json');
+    const packageFile = JSON.parse(fs_1.default.readFileSync(packagePath, 'utf8'));
+    return packageFile.version || '0.0.0';
+}
 const program = new commander_1.Command();
 program
     .name('mobilestacks')
     .description('Professional Task Runner for Stacks')
-    .version('0.1.0');
+    .version(getPackageVersion());
 program
     .command('init')
     .description('Scaffold a new mobilestacks project and config')
@@ -35,55 +77,56 @@ program.action(() => {
     console.log(chalk_1.default.bold.blue('\nMobilestacks - Professional Task Runner for Stacks\n'));
     console.log(chalk_1.default.white('USAGE: ') + chalk_1.default.green('mobilestacks <task> [options]\n'));
     console.log(chalk_1.default.bold('Available tasks:'));
-    tasks_definitions_1.TaskDefinitions.getInstance().getAllTasks().forEach(task => {
-        const params = task.params.map(p => chalk_1.default.yellow(`--${p.name}`)).join(' ');
-        console.log('  ' + chalk_1.default.cyan(task.name) + ' ' + params);
-        console.log('    ' + chalk_1.default.gray(task.description));
+    TasksDefinitions_1.TaskDefinitions.getInstance()
+        .getAllTasks()
+        .forEach((task) => {
+        const params = task.params.map((param) => chalk_1.default.yellow(`--${param.name}`)).join(' ');
+        console.log(`  ${chalk_1.default.cyan(task.name)} ${params}`);
+        console.log(`    ${chalk_1.default.gray(task.description)}`);
     });
-    console.log('\n' + chalk_1.default.white('Use ') + chalk_1.default.green('mobilestacks <task> --help') + chalk_1.default.white(' for more info on a task.'));
+    console.log(`\n${chalk_1.default.white('Use ')}${chalk_1.default.green('mobilestacks <task> --help')}${chalk_1.default.white(' for more info on a task.')}`);
     console.log(chalk_1.default.white('\nExample:'));
-    console.log('  ' + chalk_1.default.green('mobilestacks deploy-contract --contractName my-contract --file ./contracts/my-contract.clar --network testnet'));
-    console.log(chalk_1.default.white('\nDocs: ') + chalk_1.default.underline('https://github.com/your-org/mobilestacks#readme'));
+    console.log(`  ${chalk_1.default.green('mobilestacks deploycontract --contractName my-contract --file ./contracts/my-contract.clar --network testnet')}`);
+    console.log(chalk_1.default.white('\nDocs: ') + chalk_1.default.underline('https://github.com/Wizbisy/mobilestacks#readme'));
     program.help({ error: false });
 });
-tasks_definitions_1.TaskDefinitions.getInstance().getAllTasks().forEach(task => {
-    const cmd = program.command(task.name)
-        .description(task.description);
-    task.params.forEach(param => {
-        const optStr = `--${param.name} <value>`;
-        if (param.required !== false) {
-            cmd.option(optStr, param.description);
-        }
-        else {
-            cmd.option(optStr, param.description, param.defaultValue);
-        }
+TasksDefinitions_1.TaskDefinitions.getInstance()
+    .getAllTasks()
+    .forEach((task) => {
+    const cmd = program.command(task.name).description(task.description);
+    task.params.forEach((param) => {
+        const optStr = param.type === 'boolean' ? `--${param.name}` : `--${param.name} <value>`;
+        cmd.option(optStr, param.description, param.defaultValue);
     });
     cmd.action(async (opts) => {
         try {
-            const argsString = process.argv.slice(3).join(' ');
-            const unprovided = task.params.filter(p => !argsString.includes(`--${p.name}`));
-            if (unprovided.length > 0 && process.stdout.isTTY) {
-                const answers = await inquirer_1.default.prompt(unprovided.map(p => ({
-                    type: p.type === 'boolean' ? 'confirm' : 'input',
-                    name: p.name,
-                    message: p.description,
-                    default: opts[p.name] !== undefined ? opts[p.name] : p.defaultValue
+            const providedOptions = getProvidedOptions(process.argv.slice(3));
+            const missingRequiredParams = task.params.filter((param) => {
+                return param.required !== false && !providedOptions.has(param.name);
+            });
+            if (missingRequiredParams.length > 0 && process.stdout.isTTY) {
+                const answers = await inquirer_1.default.prompt(missingRequiredParams.map((param) => ({
+                    type: param.type === 'boolean' ? 'confirm' : 'input',
+                    name: param.name,
+                    message: param.description,
+                    default: opts[param.name] !== undefined ? opts[param.name] : param.defaultValue,
                 })));
                 Object.assign(opts, answers);
             }
-            task.params.forEach(p => {
-                if (opts[p.name] && p.type === 'number')
-                    opts[p.name] = Number(opts[p.name]);
-                if (opts[p.name] && p.type === 'boolean')
-                    opts[p.name] = Boolean(opts[p.name]);
+            task.params.forEach((param) => {
+                opts[param.name] = coerceParamValue(param, opts[param.name]);
+                if (param.required !== false && (opts[param.name] === undefined || opts[param.name] === '')) {
+                    throw new Error(`Missing required parameter '${param.name}'.`);
+                }
             });
-            const config = (0, config_loading_1.loadConfig)();
-            const env = new runtime_environment_1.RuntimeEnvironment(config);
+            const config = (0, ConfigLoading_1.loadConfig)();
+            const env = new RuntimeEnvironment_1.RuntimeEnvironment(config);
+            await env.ready;
             const result = await task.action(opts, env);
-            if (typeof result === 'object') {
+            if (typeof result === 'object' && result !== null) {
                 const resObj = result;
                 if (resObj.txid) {
-                    console.log(chalk_1.default.yellowBright('Transaction broadcasted to mempool! (Check explorer for final confirmation)'));
+                    console.log(chalk_1.default.yellowBright('Transaction broadcasted to mempool. Check explorer for final confirmation.'));
                 }
                 else {
                     console.log(chalk_1.default.greenBright('Success!'));

package/dist/cli/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAIA,wBAAsB,OAAO,kBA6E5B"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAmBA,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAmG7C"}