proca 2.3.1 → 2.5.0

package/README.md

@@ -48,6 +48,7 @@ you should also use the local proca-api in your [widget generator](https://githu
 
 <!-- commands -->
 * [`proca action add`](#proca-action-add)
+* [`proca action add mtt`](#proca-action-add-mtt)
 * [`proca action confirm`](#proca-action-confirm)
 * [`proca action count`](#proca-action-count)
 * [`proca action list [TITLE]`](#proca-action-list-title)
@@ -111,6 +112,7 @@ you should also use the local proca-api in your [widget generator](https://githu
 * [`proca widget add`](#proca-widget-add)
 * [`proca widget delete`](#proca-widget-delete)
 * [`proca widget external`](#proca-widget-external)
+* [`proca widget external cron`](#proca-widget-external-cron)
 * [`proca widget get`](#proca-widget-get)
 * [`proca widget list`](#proca-widget-list)
 * [`proca widget rebuild`](#proca-widget-rebuild)
@@ -162,6 +164,50 @@ EXAMPLES
   $ proca action add -i <widget_id> --firstname=John --email=john@example.org target=715a9580-cfe6-4005-9e23-61a62ddecfea --subject='MTT subject' --body='message MTT'
 ```
 
+## `proca action add mtt`
+
+```
+USAGE
+  $ proca action add mtt [ID_NAME_DXID...] -i <value> --firstname <value> --email <value>
+    [--json | --csv | --markdown] [--env <value>] [--simplify] [-n <the_short_name>] [-x <value>] [--testing] [--optin]
+    [--action_type <value>] [--lastname <value>] [--street <value>] [--locality <value>] [--region <value>] [--country
+    <value>] [--utm <value>] [--target <value>] [--subject <value>] [--body <value>]
+
+FLAGS
+  -i, --id=<value>             (required) widget's id
+  -n, --name=<the_short_name>  name (technical short name, also called slug)
+  -x, --dxid=<value>           dxid
+      --action_type=<value>    [default: email]
+      --body=<value>           [mtt] body of the email
+      --country=<value>        2-letter country iso code
+      --email=<value>          (required) email
+      --env=<value>            [default: default] allow to switch between configurations (server or users)
+      --firstname=<value>      (required) supporter's firstname
+  --lastname=<value>
+  --locality=<value>
+      --[no-]optin             Whether the user opts in (default: false). Use --optin to enable or --no-optin to
+                               explicitly disable.
+  --region=<value>
+  --street=<value>
+      --subject=<value>        [mtt] subject of the email
+      --target=<value>         [mtt] uid of the target
+      --[no-]testing           Run action in testing mode (default: true). Use --no-testing to disable.
+      --utm=<value>            utm=campaign.source.medium
+
+OUTPUT FLAGS
+  --csv            Format output as csv
+  --json           Format output as json
+  --markdown       Format output as markdown table
+  --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
+
+EXAMPLES
+  $ proca action add mtt -i <widget_id> --firstname=John --email=john@example.org
+
+  $ proca action add mtt -i <widget_id> --firstname=John --email=john@example.org --country=FR custom1=A custom2=B
+
+  $ proca action add mtt -i <widget_id> --firstname=John --email=john@example.org target=715a9580-cfe6-4005-9e23-61a62ddecfea --subject='MTT subject' --body='message MTT'
+```
+
 ## `proca action confirm`
 
 Should the supporter confirm the action? it can be set either for all the widgets or an organisation or all the widgets of a campaign
@@ -470,8 +516,8 @@ list all the campaigns
 
 ```
 USAGE
-  $ proca campaign list [--json | --csv | --markdown] [--env <value>] [--simplify] [-n
-    <name of the organisation>] [-t <campaign title>...] [--stats]
+  $ proca campaign list [NAME] [--json | --csv | --markdown] [--env <value>] [--simplify]
+    [-n <name of the organisation>] [-t <campaign title>...] [--stats]
 
 FLAGS
   -n, --name=<name of the organisation>  name (technical short name, also called slug)
@@ -1222,7 +1268,7 @@ EXAMPLES
   $ proca org logo <name of the ngo>
 ```
 
-_See code: [src/commands/org/logo.ts](https://github.com/fixthestatusquo/proca-cli/blob/v2.3.1/src/commands/org/logo.ts)_
+_See code: [src/commands/org/logo.ts](https://github.com/fixthestatusquo/proca-cli/blob/v2.5.0/src/commands/org/logo.ts)_
 
 ## `proca org user get`
 
@@ -1545,7 +1591,7 @@ _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/
 
 ## `proca service add`
 
-Set service, usually email backend for an org, the specific meaning of each param is dependant on the service
+Set service, usually email backend for an org. the specific meaning of each param is dependant on the service. 
 
 ```
 USAGE
@@ -1559,7 +1605,7 @@ FLAGS
       --host=<value>      server of the service
       --password=<value>  credential of the account on the service
       --path=<value>      path on the service
-      --type=<option>     (required) [default: system] type of the service
+      --type=<option>     (required) type of the service
                           <options: mailjet|ses|stripe|test_stripe|preview|webhook|supabase|smtp>
       --user=<value>      credential of the account on the service
 
@@ -1570,7 +1616,15 @@ OUTPUT FLAGS
   --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
 
 DESCRIPTION
-  Set service, usually email backend for an org, the specific meaning of each param is dependant on the service
+  Set service, usually email backend for an org. the specific meaning of each param is dependant on the service.
+  If a service from that type exists, it will replace it
+
+EXAMPLES
+  $ proca service add -o example_org --type system
+
+  $ proca service add -o example_org --host=tls://mail.example.org:587 --user=login --password "secret" --type smtp
+
+  $ proca service add -o example_org --host=ssl://mail.example.org:465 --user=login --password "secret" --type smtp
 ```
 
 ## `proca service list`
@@ -1970,6 +2024,34 @@ EXAMPLES
   $ proca widget external --url https://mitmachen.wwf.de/node/506/polling
 ```
 
+## `proca widget external cron`
+
+Pull all external counters and save it into a widget extra Supporter. symlink the widget json into config/counter
+
+```
+USAGE
+  $ proca widget external cron [--json | --csv | --markdown] [--env <value>] [--simplify]
+    [--dry-run]
+
+FLAGS
+  --dry-run      just fetch, don't update
+  --env=<value>  [default: default] allow to switch between configurations (server or users)
+
+OUTPUT FLAGS
+  --csv            Format output as csv
+  --json           Format output as json
+  --markdown       Format output as markdown table
+  --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
+
+DESCRIPTION
+  Pull all external counters and save it into a widget extra Supporter. symlink the widget json into config/counter
+
+EXAMPLES
+  $ proca widget external cron
+```
+
+_See code: [src/commands/widget/external/cron.ts](https://github.com/fixthestatusquo/proca-cli/blob/v2.5.0/src/commands/widget/external/cron.ts)_
+
 ## `proca widget get`
 
 view a widget

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "proca",
   "description": "Access the proca api",
-  "version": "2.3.1",
+  "version": "2.5.0",
   "author": "Xavier",
   "bin": {
     "proca": "proca-cli"
@@ -21,6 +21,7 @@
     "merge-anything": "^6.0.6",
     "object-path": "^0.11.8",
     "prompts": "^2.4.2",
+    "simple-git": "^3.33.0",
     "typescript": "^5.7.3",
     "urql": "^4.1.0"
   },

package/src/commands/action/add/mtt.mjs

@@ -0,0 +1,192 @@
+import { Args, Flags } from "@oclif/core";
+import { error, stdout, ux } from "@oclif/core/ux";
+import Command from "#src/procaCommand.mjs";
+import { gql, mutation } from "#src/urql.mjs";
+import { getTwitter } from "#src/util/twitter.mjs";
+
+export default class ActionAdd extends Command {
+  static examples = [
+    "<%= config.bin %> <%= command.id %> -i <widget_id> --firstname=John --email=john@example.org",
+    "<%= config.bin %> <%= command.id %> -i <widget_id> --firstname=John --email=john@example.org --country=FR custom1=A custom2=B",
+    "<%= config.bin %> <%= command.id %> -i <widget_id> --firstname=John --email=john@example.org target=715a9580-cfe6-4005-9e23-61a62ddecfea --subject='MTT subject' --body='message MTT'",
+  ];
+
+  static args = this.multiid();
+  static strict = false; //THIS DOES NOT WORK
+
+  static flags = {
+    ...this.flagify({ multiid: true }),
+    id: Flags.integer({
+      char: "i",
+      description: "widget's id",
+      required: true,
+    }),
+    testing: Flags.boolean({
+      default: true,
+      allowNo: true, // ✅ enables --no-testing
+      description:
+        "Run action in testing mode (default: true). Use --no-testing to disable.",
+    }),
+    optin: Flags.boolean({
+      default: false,
+      allowNo: true, // ✅ enables --no-optin
+      description:
+        "Whether the user opts in (default: false). Use --optin to enable or --no-optin to explicitly disable.",
+    }),
+    action_type: Flags.string({
+      default: "email",
+    }),
+    firstname: Flags.string({
+      description: "supporter's firstname",
+      required: true,
+    }),
+    lastname: Flags.string(),
+    street: Flags.string(),
+    locality: Flags.string(),
+    region: Flags.string(),
+    country: Flags.string({
+      description: "2-letter country iso code",
+      parse: async (input) => {
+        if (input && !/^[A-Za-z]{2}$/.test(input)) {
+          throw new Error("Country code must be exactly 2 letters");
+        }
+        return input?.toUpperCase(); // optional: normalize to uppercase
+      },
+    }),
+    utm: Flags.string({
+      description: "utm=campaign.source.medium",
+    }),
+    email: Flags.string({
+      description: "email",
+      required: true,
+    }),
+    target: Flags.string({ description: "[mtt] uid of the target" }),
+    subject: Flags.string({ description: "[mtt] subject of the email" }),
+    body: Flags.string({ description: "[mtt] body of the email" }),
+  };
+
+  create = async (flags) => {
+    const values = {
+      action: {
+        actionType: flags.action_type,
+        customFields: flags.customFields,
+        /*    "mtt": {
+      "body": "body",
+      "files": [
+        "files"
+      ],
+      "subject": "subject",
+      "targets": [
+        "targets"
+      ]
+    },
+*/
+        testing: flags.testing,
+      },
+      actionPageId: flags.id,
+      contact: {
+        address: {
+          country: flags.country,
+          locality: flags.locality,
+          postcode: flags.postcode,
+          region: flags.region,
+          street: flags.street,
+          //      "streetNumber": "streetNumber"
+        },
+        email: flags.email,
+        firstName: flags.firstname,
+        lastName: flags.lastname,
+        phone: flags.phone,
+      },
+      privacy: {
+        //    "leadOptIn": true,
+        optIn: flags.optin,
+      },
+      tracking: {
+        ...flags.tracking,
+        location: "proca-cli/action/add",
+      },
+    };
+
+    if (flags.target) {
+      values.action.mtt = {
+        targets: [flags.target],
+        subject: flags.subject || "Test MTT",
+        body: flags.body || "Please ignore, this is a test",
+      };
+      values.action.actionType = "mail2target";
+    }
+    console.log(values.action.mtt);
+
+    const query = gql`
+ mutation (
+  $action: ActionInput!
+  $actionPageId: Int!
+  $contact: ContactInput!
+  $contactRef: ID
+  $privacy: ConsentInput!
+  $tracking: TrackingInput
+) {
+  addActionContact(
+    action: $action
+    actionPageId: $actionPageId
+    contact: $contact
+    contactRef: $contactRef
+    privacy: $privacy
+    tracking: $tracking
+  ) {
+    contactRef
+    firstName
+  }
+}`;
+
+    const result = await mutation(query, values);
+
+    console.log("result", result);
+    return result;
+  };
+
+  parseUnknownFlags = (argv) => {
+    const knownFlags = Object.entries(ActionAdd.flags).flatMap(([key, def]) => {
+      const chars = def.char ? [def.char] : [];
+      return [key, ...chars];
+    });
+    /* doesn't work static=false has no effect    const unknownFlags = Object.fromEntries(
+      argv
+        .filter(arg =>
+          (/^--?\w+=/.test(arg)) // --key=val or -x=val
+        )
+        .map(arg => {
+          const keyval = arg.replace(/^-+/, '').split('=')
+          return [keyval[0], keyval[1]]
+        })
+        .filter(([key]) => !knownFlags.includes(key))
+    )
+*/
+
+    // Extract key=val style positional args (e.g. foo=bar)
+    const kvArgs = Object.fromEntries(
+      argv
+        .filter((arg) => !arg.startsWith("-") && arg.includes("="))
+        .map((arg) => arg.split("=")),
+    );
+
+    if (!Object.keys(kvArgs).length) return undefined;
+
+    return kvArgs;
+  };
+  async run() {
+    const { args, flags } = await this.parse(ActionAdd, {
+      context: { strict: false /* this does not work*/ },
+    });
+
+    const customFields = this.parseUnknownFlags(this.argv);
+    if (customFields) flags.customFields = JSON.stringify(customFields);
+    if (flags.utm) {
+      const [campaign, source, medium] = flags.utm.split(".");
+      flags.tracking = { source, medium, campaign };
+    } else flags.tracking = {};
+    const data = await this.create(flags);
+    return this.output(data);
+  }
+}

package/src/commands/campaign/get.mjs

@@ -62,6 +62,7 @@ export default class CampaignGet extends Command {
       name: name,
       withStats: this.flags.stats,
     });
+    result.campaign.config = JSON.parse(result.campaign.config);
     return result.campaign;
   };
 
@@ -108,7 +109,6 @@ export default class CampaignGet extends Command {
   };
 
   table = (r) => {
-    r.config = JSON.parse(r.config);
     super.table(r, null, null);
     if (this.flags.locale) {
       this.prettyJson(r.config?.locales[this.flags.locale]);

package/src/commands/campaign/list.mjs

@@ -18,11 +18,11 @@ export default class CampaignList extends Command {
 
   static description = "list all the campaigns";
 
-  //  static args = this.multiid();
+  static args = this.namearg();
 
   static flags = {
     // flag with no value (-f, --force)
-    ...this.flagify({ name: "name of the organisation" }),
+    ...this.flagify({ name: "name of the organisation", char: "o" }),
     title: Flags.string({
       char: "t",
       description: "name of the campaign",
@@ -111,7 +111,7 @@ export default class CampaignList extends Command {
 
     if (!flags.title && !flags.name) {
       throw new Error(
-        `${this.id} -t [title of the campaign] or -o [organisation]`,
+        `${this.id} -t [title of the campaign] or -n [organisation]`,
       );
     }
 

package/src/commands/service/add.mjs

@@ -1,6 +1,6 @@
 import { Flags } from "@oclif/core";
 import Command from "#src/procaCommand.mjs";
-import { gql, mutation, query } from "#src/urql.mjs";
+import { gql, mutation } from "#src/urql.mjs";
 
 const SERVICE_NAMES = [
   "MAILJET",
@@ -14,9 +14,19 @@ const SERVICE_NAMES = [
   "SMTP",
 ].map((d) => d.toLowerCase());
 
-export default class OrgEmail extends Command {
+export default class ServiceAdd extends Command {
   static description =
-    "Set service, usually email backend for an org, the specific meaning of each param is dependant on the service";
+    "Set service, usually email backend for an org. the specific meaning of each param is dependant on the service. \nIf a service from that type exists, it will replace it";
+
+  // examples to add to help
+  // <%= config.bin %> resolves to the executable name
+  // <%= command.id %> resolves to the command name
+  static examples = [
+    // Examples can be simple strings
+    "<%= config.bin %> <%= command.id %> -o example_org --type system",
+    '<%= config.bin %> <%= command.id %> -o example_org --host=tls://mail.example.org:587 --user=login --password "secret" --type smtp',
+    '<%= config.bin %> <%= command.id %> -o example_org --host=ssl://mail.example.org:465 --user=login --password "secret" --type smtp',
+  ];
 
   static flags = {
     ...super.globalFlags,
@@ -29,7 +39,6 @@ export default class OrgEmail extends Command {
       description: "type of the service",
       options: SERVICE_NAMES,
       required: true,
-      default: "system",
     }),
     user: Flags.string({
       description: "credential of the account on the service",
@@ -37,7 +46,7 @@ export default class OrgEmail extends Command {
     password: Flags.string({
       description: "credential of the account on the service",
     }),
-    host: Flags.string({
+    host: Flags.url({
       description: "server of the service",
     }),
     path: Flags.string({

package/src/commands/widget/external/cron.js

@@ -0,0 +1,63 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Flags } from "@oclif/core";
+import { update } from "#src/commands/widget/external/index.mjs";
+import Command from "#src/procaCommand.mjs";
+
+export default class CounterExternal extends Command {
+  static description =
+    "Pull all external counters and save it into a widget extra Supporter. symlink the widget json into config/counter";
+
+  static examples = ["<%= config.bin %> <%= command.id %>"];
+
+  static flags = {
+    "dry-run": Flags.boolean({
+      description: "just fetch, don't update",
+    }),
+  };
+
+  async monitored() {
+    const dir = path.join(this.config.procaConfig.folder, "/counter");
+    try {
+      await fs.access(dir);
+    } catch {
+      this.error(`create the folder ${dir}`);
+    }
+    const entries = await fs.readdir(dir);
+    const results = await Promise.all(
+      entries.map(async (entry) => {
+        const file = entry.split(".");
+        if (file.length !== 2) {
+          this.warn(`invalid file ${entry}`);
+          return;
+        }
+        if (file[1] !== "json") {
+          this.warn(`should be a json file ${entry}`);
+          return;
+        }
+        const content = JSON.parse(
+          await fs.readFile(path.join(dir, entry), "utf-8"),
+        );
+        return {
+          id: Number.parseInt(file[0]),
+          name: content.filename,
+          url: content.component.counter?.url,
+          path: content.component.counter?.path,
+        };
+      }),
+    );
+    return results.flat();
+  }
+
+  async run() {
+    const { flags } = await this.parse(CounterExternal);
+    const widgets = await this.monitored();
+    if (flags["dry-run"]) return this.output(widgets);
+    const updated = await Promise.all(
+      widgets.map(async (widget) => {
+        return await update(widget);
+      }),
+    );
+    return this.output(updated);
+  }
+}

package/src/commands/widget/external/index.mjs

@@ -1,8 +1,19 @@
-import { readFile } from "node:fs/promises";
 import { Flags } from "@oclif/core";
 import oPath from "object-path";
 import { updateCounter } from "#src/commands/widget/update/external.mjs";
-import Command from "#src/procaCommand.mjs";
+import Command from "#src/gitCommand.mjs";
+
+export const update = async (config) => {
+  const d = new CounterExternal([]);
+  //      const config = await d.getCounterConfig({id});
+  if (!config) {
+    console.warn("missing config");
+    return undefined;
+  }
+  const counter = await d.fetchCounter(config);
+  await updateCounter(config.id, counter);
+  return { name: config.name, counter, id: config.id };
+};
 
 export default class CounterExternal extends Command {
   static description =
@@ -41,47 +52,59 @@ export default class CounterExternal extends Command {
     }),
   };
 
-  async fetchCounter({ url, path, timeout, "dry-run": verbose }) {
-    const response = await fetch(url, {
-      timeout,
-      headers: {
-        "User-Agent": "proca",
-      },
-    });
-
-    if (!response.ok) {
-      this.error(`API request failed with status ${response.status}`, {
-        exit: 1,
+  async fetchCounter({ url, path, timeout = 10000, "dry-run": verbose }) {
+    try {
+      const response = await fetch(url, {
+        signal: AbortSignal.timeout(timeout),
+        headers: {
+          "User-Agent": "proca/451.42",
+        },
       });
-    }
+      if (!response.ok) {
+        this.error(`API request failed with status ${response.status}`, {
+          exit: 1,
+        });
+      }
 
-    const data = await response.json();
-    if (verbose) {
-      this.log(JSON.stringify(data, null, 2));
+      const data = await response.json();
+      if (verbose) {
+        this.log(JSON.stringify(data, null, 2));
+      }
+      const counter = oPath.get(data, path);
+      if (
+        Number.isNaN(Number.parseFloat(counter)) ||
+        !Number.isFinite(counter)
+      ) {
+        this.error(`Could not extract value from ${counter} at ${path}`, {
+          exit: 1,
+        });
+      }
+      return Number.parseFloat(counter);
+    } catch (err) {
+      if (err.name === "TimeoutError") {
+        console.error("Request timed out after", timeout, "ms");
+      } else if (err.cause?.code === "ETIMEDOUT") {
+        console.error("Network timeout — server unreachable:", url);
+      } else {
+        throw err;
+      }
     }
-    const counter = oPath.get(data, path);
-    if (Number.isNaN(Number.parseFloat(counter)) || !Number.isFinite(counter)) {
-      this.error(`Could not extract value from ${counter} at ${path}`, {
-        exit: 1,
-      });
-    }
-    return Number.parseFloat(counter);
   }
 
-  async getCounterConfig(id) {
-    const folder = this.procaConfig.folder;
-    const filePath = `${folder}/${id}.json`;
-
-    const data = await readFile(filePath, "utf8");
-    const jsonData = JSON.parse(data);
-    return jsonData.component.counter;
+  async getCounterConfig() {
+    const data = await this.read();
+    if (!data.component.counter)
+      this.error(
+        "missing config.component.counter {url, path} in ${this.getFile()}",
+      );
+    return data.component.counter;
   }
 
   async run() {
     const { flags } = await this.parse(CounterExternal);
     let counter = undefined;
-    if (!flags.url) {
-      const config = await this.getCounterConfig(flags.id);
+    if (!flags.url && !flags.total) {
+      const config = await this.getCounterConfig();
       flags.url = config.url;
       flags.path = config.path;
     }

package/src/gitCommand.mjs

@@ -0,0 +1,173 @@
+import fs from "node:fs";
+//import { load as loadConfig } from "proca/src/config.mjs";
+import path from "node:path";
+import chalk from "chalk";
+import simpleGit from "simple-git";
+import ProcaCommand from "#src/procaCommand.mjs";
+export { Args, Flags } from "#src/index.mjs";
+
+export class ProcaGitCommand extends ProcaCommand {
+  fileName = undefined;
+  newFile = undefined;
+
+  static extension = "json";
+
+  initGit = () => {
+    if (!fs.existsSync(path.join(this.config.procaConfig.folder, "/.git"))) {
+      this.warn("config not on git");
+    }
+    return simpleGit({ baseDir: this.config.procaConfig.folder });
+  };
+
+  commit = async () => this.git.commit(this.gitMessage(), [this.getFile()]);
+
+  checkFile = (fileName) => {
+    if (fileName.toString().includes("..")) {
+      this.error("invalid filename ", fileName);
+    }
+    return fileName;
+  };
+  // mkdir -p
+  mkdirp = () => {
+    fs.mkdirSync(this.getFile(), { recursive: true });
+  };
+
+  getFolder = () => {
+    const mapping = { widget: "./", campaign: "campaign/", org: "org/" };
+    const type = this.id.split(":")[0];
+    const folder = mapping[type];
+    if (!folder) this.error(`no folder defined for ${type}`);
+    return folder;
+  };
+
+  setFile = (name, ext = "json") => {
+    if (!name) {
+      const folder = this.getFolder();
+      if (folder === "./") {
+        //we are dealing with widgets
+        name = `${folder}${this._flags.id}`;
+      } else {
+        name = `${folder}${this._flags.name}`;
+      }
+    }
+    this.fileName = path.join(
+      this.config.procaConfig.folder,
+      `${this.checkFile(name)}.${ext}`,
+    );
+    return this.fileName;
+  };
+
+  getFile = () => {
+    if (!this.fileName) this.error("you need to setFile first");
+    return this.fileName;
+  };
+
+  gitMessage = (_obj) => `proca cli ${this.id}`;
+
+  fileExists = () => {
+    return fs.existsSync(this.getFile());
+  };
+
+  uncommited = async ({ file, commit = false, exit = true }) => {
+    if (!this.git) return false;
+    if (!file) file = this.getFile();
+    const status = await this.git.status();
+    const relative = path.relative(this.config.procaConfig.folder, file);
+
+    const hasChanges = status.modified.includes(relative);
+    if (!hasChanges) return false;
+    if (commit) {
+      this.git.commit(this.gitMessage(data, file));
+    }
+    if (exit) {
+      this.log(await this.diff(file));
+      this.error(`Your local changes to ${file} would be overwritten`, {
+        code: "git error",
+        exit: 1,
+        suggestions: ["run with --auto to commit the changes before pulling"],
+      });
+    }
+    return true;
+  };
+
+  read = async ({ file = this.getFile(), commit } = {}) => {
+    try {
+      let data;
+      if (!file) file = getFile();
+      const ext = this.constructor.extension;
+      console.log("read file", file, ext);
+      if (ext === "json") {
+        data = JSON.parse(fs.readFileSync(file, "utf8"));
+      } else {
+        data = fs.readFileSync(file, "utf8");
+      }
+      if (commit && this.git) {
+        const status = await this.git.status();
+        const hasChanges = status.modified.includes(file);
+        if (hasChanges) {
+          this.git.commit(this.gitMessage(data, file));
+        }
+      }
+      return data;
+    } catch (e) {
+      console.error(`no local copy of ${file}: ${e.message}`);
+      return null;
+    }
+  };
+
+  stringify = (obj) =>
+    `${JSON.stringify(
+      obj,
+      (_key, value) => (value === null ? undefined : value),
+      2,
+    )}\n`;
+
+  diff = async (file) => {
+    const diff = await this.git.diff([file || this.getFile()]);
+    const colorDiff = diff
+      .split("\n")
+      .map((line) => {
+        if (line.startsWith("+")) return chalk.green(line);
+        if (line.startsWith("-")) return chalk.red(line);
+        if (line.startsWith("@@")) return chalk.cyan(line);
+        return line;
+      })
+      .join("\n");
+    return colorDiff;
+  };
+
+  save = async (json) => {
+    let needToAdd = false;
+    const file = this.getFile();
+    if (this.git && !this.fileExists(file)) {
+      needToAdd = true;
+    }
+    this.uncommited({ file }); //exit if unsaved, better to always stash?
+    fs.writeFileSync(file, this.stringify(json));
+    if (this.git) {
+      if (needToAdd) {
+        await this.git.add(file);
+      }
+      const diff = await this.diff(file);
+      const r = await this.git.commit(this.gitMessage(json), file);
+      return { ...r, ...r.summary, diff };
+    }
+    return { file, git: false };
+  };
+
+  parse = async () => {
+    const r = await super.parse();
+    if (this._flags.git === false) {
+      this.git = undefined;
+    }
+    this._flags && this.setFile(null, this.constructor.extension);
+    return r;
+  };
+
+  async init() {
+    await super.init();
+    this.git = this.initGit();
+  }
+}
+
+export default ProcaGitCommand;

package/src/index.d.mts

@@ -0,0 +1 @@
+export { run, Args, Flags } from "@oclif/core";

package/src/procaCommand.mjs

@@ -10,7 +10,8 @@ class ProcaCommand extends Command {
   static enableJsonFlag = true;
   procaConfig = { url: "https://api.proca.app/api" };
   format = "human"; // the default formatting
-  flags = {};
+  flags = {}; // the definition
+  _flags = undefined; // the cli flags
 
   static baseFlags = {
     env: Flags.string({
@@ -50,6 +51,17 @@ class ProcaCommand extends Command {
     return args;
   }
 
+  static namearg() {
+    const args = {
+      name: Args.string({
+        ignoreStdin: true,
+        hidden: true,
+        description: "convenience, but try to use -n <name> instead",
+      }),
+    };
+    return args;
+  }
+
   static flagify({ multiid = false, name = false, char } = {}) {
     const flags = Object.assign({}, ProcaCommand.baseFlags);
     if (name || multiid) {
@@ -86,9 +98,14 @@ class ProcaCommand extends Command {
 
   async parse() {
     const parsed = await super.parse();
+
+    if (parsed.args.name)
+      parsed.flags.name = ProcaCommand.safeName(parsed.args.name);
+
     if (this.ctor.args.id_name_dxid === undefined) {
       return parsed;
     }
+
     const maybe = parsed.args.id_name_dxid;
     if (maybe) {
       const identified = [
@@ -106,9 +123,11 @@ class ProcaCommand extends Command {
       if (d) parsed.flags.id = d;
       else parsed.flags.name = ProcaCommand.safeName(maybe);
     }
+
     if (parsed.flags.dxid) {
       parsed.flags.id = dxid(parsed.flags.dxid);
     }
+
     const identified = [
       parsed.flags.name,
       parsed.flags.id,
@@ -120,7 +139,7 @@ class ProcaCommand extends Command {
         code: 1,
       });
     }
-
+    this._flags = parsed.flags;
     return parsed;
   }
 
@@ -132,16 +151,16 @@ class ProcaCommand extends Command {
   };
   async init() {
     await super.init();
+    this.debug = debug("proca");
+    initHook({ config: this.config });
+    this.procaConfig = this.config.procaConfig; // set up from the hooks/init
+    //    await this.config.runHook('init', { config: this.config });
     const { flags } = await this.parse();
     this.flags = flags;
     if (flags.json) this.format = "json";
     if (flags.csv) this.format = "csv";
     if (flags.markdown) this.format = "markdown";
 
-    this.debug = debug("proca");
-    initHook({ config: this.config });
-    this.procaConfig = this.config.procaConfig; // set up from the hooks/init
-    //    await this.config.runHook('init', { config: this.config });
     createClient(this.procaConfig);
   }
 
@@ -192,7 +211,7 @@ class ProcaCommand extends Command {
     for (const [key, value] of Object.entries(d)) {
       if (key === "__typename") continue;
       if (key === "config" && typeof value === "string") continue; // it's just a giant mess if not processed, let's skipt
-      if (value === null) continue;
+      if (value === null || value === "") continue;
       if (typeof value === "string" || typeof value === "number") {
         r[key] = value;
         continue;