npm package: @o-town/devkit
Description: Zero-dependency Node.js debug inspector and test runner
Author: o-town
Latest version: 1.3.1

# DevKit — Node.js Debug & Test Runner

A zero-dependency Node.js package with a rich debug inspector and a built-in test runner.

---

## Quick Start

```bash
npm run debug     # inspect system, env, package, dependencies & file structure
npm run tester    # run all test suites in tests/
```

---

## `npm run debug`

Prints a full runtime report:

| Section              | What it shows                                      |
|----------------------|----------------------------------------------------|
| System Snapshot      | Platform, Node version, PID, CPU count, memory     |
| Package Info         | name, version, main, scripts                       |
| Dependencies         | Whether each declared dep is installed or missing  |
| Environment Vars     | Relevant `process.env` keys                        |
| Project Structure    | File tree (skips `node_modules`, dotfiles)         |
| Summary              | Any warnings/errors found                          |

All output is also saved to `logs/debug-YYYY-MM-DD.log`.

---

## `npm run tester`

- Scans `tests/*.test.js` and runs every suite automatically.
- Falls back to built-in example tests when no files are found.
- Zero dependencies — no Jest, no Mocha needed.

### Writing Tests

```js
// tests/my-feature.test.js

describe('My Feature', () => {

  beforeEach(() => { /* setup */ });

  it('adds numbers', (assert) => {
    assert.equal(1 + 1, 2);
  });

  it('checks an object', (assert) => {
    assert.deepEqual({ a: 1 }, { a: 1 });
  });

  xit('this test is skipped');
});
```

### Assert API

| Method                          | Description                                 |
|---------------------------------|---------------------------------------------|
| `assert.equal(a, b, msg?)`      | Strict equality (`===`)                     |
| `assert.notEqual(a, b, msg?)`   | Strict inequality                           |
| `assert.deepEqual(a, b, msg?)`  | Deep equality via JSON serialization        |
| `assert.truthy(val, msg?)`      | Value is truthy                             |
| `assert.falsy(val, msg?)`       | Value is falsy                              |
| `assert.throws(fn, msg?)`       | Sync function throws                        |
| `assert.asyncThrows(fn, msg?)`  | Async function throws                       |
| `assert.typeOf(val, type, msg?)`| `typeof` check                              |
| `assert.instanceOf(v, cls, msg?)`| `instanceof` check                         |
| `assert.includes(arr, item, msg?)`| Array includes item                       |
| `assert.match(str, regex, msg?)`| Regex test                                  |

### Lifecycle Hooks

```js
beforeAll(fn)   // runs once before the suite
afterAll(fn)    // runs once after the suite
beforeEach(fn)  // runs before every test
afterEach(fn)   // runs after every test
```

---

## File Structure

```
devkit/
├── package.json
├── src/
│   ├── index.js       ← programmatic API (logger, assert, info)
│   ├── debug.js       ← npm run debug
│   └── tester.js      ← npm run tester
├── tests/
│   └── example.test.js
└── logs/              ← auto-created on first debug run
```
---
### change package,json 
```
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node server.js",
    "debug": "node node_modules/@o-town/devkit/debug.js",
    "tester": "node node_modules/@o-town/devkit/tester.js"
  },
```
---
## Programmatic Use

```js
const { logger, assert, info } = require('./src/index');

logger.info('Server started');
logger.ok('DB connected');
logger.warn('Config missing, using defaults');
logger.error('Unhandled exception');
logger.debug('payload: ' + JSON.stringify(data));

assert.equal(user.role, 'admin');

console.log(info());
```